Frauddi API

The Frauddi API is organized around REST with predictable resource-oriented URLs, JSON-encoded request bodies, and standard HTTP response codes.

Our API provides programmatic access to fraud detection, rule management, entity relationship mapping, and operational analytics.

Base URL: https://api.frauddi.com

Authentication

To authorize, use this code:

curl "https://api.frauddi.com/api/v0/endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.frauddi.com/api/v0/endpoint', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    // request data
  })
});
const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    # request data
}

response = requests.post(
    'https://api.frauddi.com/api/v0/endpoint',
    headers=headers,
    json=data
)
result = response.json()

All API requests require authentication using your API key in the Authorization header.

Contact our sales team or access your Frauddi dashboard to obtain your API key.

Authorization: Bearer YOUR_API_KEY

Getting Started

1. Obtain your API key from our sales team or dashboard
2. Make a test request to the /ping endpoint
   
3. Submit transaction data to /assessments/ endpoints
4. Configure detection rules via /rules/ endpoints

Response Format

All API responses use standard HTTP status codes and return JSON-encoded data with consistent error handling.

Frauddi API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Frauddi API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Authentication

Authenticate API requests using your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Making Requests

All API requests should be made over HTTPS to the base URL. Request and response bodies are JSON.

Response Format

All API responses follow a consistent structure with appropriate HTTP status codes. Successful requests return relevant data objects, while errors return detailed error information.

Getting Started

1. Obtain your API key from the Frauddi dashboard or by contacting our sales team
2. Make a test request to the health check endpoint
3. Submit transaction data to assessment endpoints
4. Configure rules and thresholds for your use case

Base URLs:

• https://api.frauddi.com

Email: Frauddi Support Web: Frauddi Support

Authentication

• HTTP Authentication, scheme: bearer

Default

Main

GET /

Main endpoint for the application.

Example responses

200 Response

{}

Responses

Response Schema

Status Code 200

Response Main Get

Pong

GET /ping

Ping/Pong endpoint for the application.

Example responses

200 Response

{}

Responses

Response Schema

Status Code 200

Response Pong Ping Get

Assessments

Assess Charge for Fraud Risk

POST /api/v1/assessments/charges

Submit a payment charge for real-time fraud assessment.

This endpoint processes the charge through multiple detection layers: - Whitelist/Blacklist checking - Verify against trusted and blocked entities - Rule Engine - Apply custom fraud detection rules - Pattern Recognition - Advanced anomaly detection and fraud patterns - Network Analysis - Relationship analysis and behavior patterns - Email Validation - Email risk assessment and verification

Returns a comprehensive risk assessment with decision rationale and score.

Body parameter

{
  "charge_id": "ch_1234567890",
  "status": "pending",
  "customer": {
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "email": "customer@example.com",
    "ip_address": "192.168.1.1",
    "fingerprint": "fp_1234abcd5678efgh"
  },
  "payment": {
    "currency": "USD",
    "amount": 100.5,
    "fee": 2.5,
    "card_hash": "hash_1a2b3c4d5e6f",
    "card_type": "credit",
    "exp_month": "01",
    "brand": "visa",
    "bin_number": "424242",
    "cvc": "123"
  },
  "metadata": {
    "campaign_id": "summer_sale_2024",
    "checkout_steps": 3,
    "customer_tier": "premium",
    "referral_source": "google_ads",
    "session_duration": 1200
  }
}

Parameters

Example responses

200 Response

{
  "decision": "ACCEPT",
  "score": 0.15,
  "decided_by": {
    "module": "RULES",
    "priority": 1,
    "decision": "ACCEPT"
  },
  "assessment_id": "550e8400-e29b-41d4-a716-446655440000",
  "details": {
    "whitelists": {
      "decision": "NO_DECISION"
    },
    "blacklists": {
      "decision": "NO_DECISION"
    },
    "rules": {
      "decision": "ACCEPT",
      "matched_rules": [
        "rule_1"
      ]
    }
  }
}

Responses

Assess Email Risk

POST /api/v1/assessments/emails

Validate and assess risk for customer email addresses.

This endpoint analyzes email addresses for: - Domain reputation - Check email domain against threat databases - Disposable email detection - Identify temporary or throwaway emails - Syntax validation - Verify email format and structure - Risk scoring - Calculate fraud probability based on email patterns

Returns assessment with email-specific risk indicators and recommendations.

Body parameter

{
  "charge_id": "ch_1234567890",
  "status": "pending",
  "customer": {
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "email": "customer@example.com",
    "ip_address": "192.168.1.1",
    "fingerprint": "fp_1234abcd5678efgh"
  },
  "payment": {
    "currency": "USD",
    "amount": 100.5,
    "fee": 2.5,
    "card_hash": "hash_1a2b3c4d5e6f",
    "card_type": "credit",
    "exp_month": "01",
    "brand": "visa",
    "bin_number": "424242",
    "cvc": "123"
  },
  "metadata": {
    "campaign_id": "summer_sale_2024",
    "checkout_steps": 3,
    "customer_tier": "premium",
    "referral_source": "google_ads",
    "session_duration": 1200
  }
}

Parameters

Example responses

200 Response

{
  "decision": "ACCEPT",
  "assessment_id": "550e8400-e29b-41d4-a716-446655440000",
  "assessment_type": "EMAIL",
  "decided_by": {
    "module": "EMAIL",
    "priority": 1,
    "decision": "ACCEPT"
  },
  "decision_details": {
    "EMAIL": {
      "result": {
        "is_valid": true,
        "is_disposable": false,
        "domain_reputation": "good"
      }
    }
  }
}

Responses

Assess Risk Using Rules

POST /api/v1/assessments/rules

Evaluate transaction risk using your custom fraud detection rules.

This endpoint applies all active rules configured for your company and returns: - Rule evaluation results - Which rules matched and their outcomes - Decision hierarchy - Rule priority and decision logic - Custom logic execution - Business rules processing - Threshold analysis - Rule confidence scores and thresholds

Rules are processed in priority order and can trigger various actions (ACCEPT, REVIEW, DECLINE).

Body parameter

{
  "charge_id": "ch_1234567890",
  "status": "pending",
  "customer": {
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "email": "customer@example.com",
    "ip_address": "192.168.1.1",
    "fingerprint": "fp_1234abcd5678efgh"
  },
  "payment": {
    "currency": "USD",
    "amount": 100.5,
    "fee": 2.5,
    "card_hash": "hash_1a2b3c4d5e6f",
    "card_type": "credit",
    "exp_month": "01",
    "brand": "visa",
    "bin_number": "424242",
    "cvc": "123"
  },
  "metadata": {
    "campaign_id": "summer_sale_2024",
    "checkout_steps": 3,
    "customer_tier": "premium",
    "referral_source": "google_ads",
    "session_duration": 1200
  }
}

Parameters

Example responses

200 Response

{
  "decision": "REVIEW",
  "assessment_id": "550e8400-e29b-41d4-a716-446655440000",
  "assessment_type": "RULE",
  "decided_by": {
    "module": "RULES",
    "priority": 1,
    "decision": "REVIEW"
  },
  "decision_details": {
    "RULES": {
      "result": {
        "matched_rules": [
          "high_amount_rule",
          "new_customer_rule"
        ],
        "rule_scores": {
          "high_amount_rule": 0.8,
          "new_customer_rule": 0.6
        },
        "final_score": 0.85
      }
    }
  }
}

Responses

Check Against Blacklists

POST /api/v1/assessments/blacklists

Check transaction and customer data against your company's blacklists.

This endpoint validates multiple data points against blacklisted entities: - Email addresses - Blocked customer emails - IP addresses - Suspicious or blocked IPs - Card numbers - Blocked payment methods (hashed for security) - Phone numbers - Blocked customer phone numbers - Device fingerprints - Blocked devices or browsers

Returns immediate DECLINE decision if any blacklisted entity is detected.

Body parameter

{
  "charge_id": "ch_1234567890",
  "status": "pending",
  "customer": {
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "email": "customer@example.com",
    "ip_address": "192.168.1.1",
    "fingerprint": "fp_1234abcd5678efgh"
  },
  "payment": {
    "currency": "USD",
    "amount": 100.5,
    "fee": 2.5,
    "card_hash": "hash_1a2b3c4d5e6f",
    "card_type": "credit",
    "exp_month": "01",
    "brand": "visa",
    "bin_number": "424242",
    "cvc": "123"
  },
  "metadata": {
    "campaign_id": "summer_sale_2024",
    "checkout_steps": 3,
    "customer_tier": "premium",
    "referral_source": "google_ads",
    "session_duration": 1200
  }
}

Parameters

Example responses

200 Response

{
  "decision": "DECLINE",
  "assessment_id": "550e8400-e29b-41d4-a716-446655440000",
  "assessment_type": "BLACKLIST",
  "decided_by": {
    "module": "BLACKLISTS",
    "priority": 1,
    "decision": "DECLINE"
  },
  "decision_details": {
    "BLACKLISTS": {
      "result": {
        "matches_found": [
          "email",
          "ip_address"
        ],
        "blacklisted_email": "fraud@example.com",
        "blacklisted_ip": "192.168.1.100"
      }
    }
  }
}

Responses

Check Against Whitelists

POST /api/v1/assessments/whitelists

Check transaction and customer data against your company's whitelists.

This endpoint validates multiple data points against trusted entities: - Email addresses - Trusted customer emails - IP addresses - Trusted or corporate IPs - Card numbers - Trusted payment methods (hashed for security) - Phone numbers - Verified customer phone numbers - Device fingerprints - Trusted devices or browsers

Returns immediate ACCEPT decision if any whitelisted entity is detected, bypassing other fraud checks.

Body parameter

{
  "charge_id": "ch_1234567890",
  "status": "pending",
  "customer": {
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "email": "customer@example.com",
    "ip_address": "192.168.1.1",
    "fingerprint": "fp_1234abcd5678efgh"
  },
  "payment": {
    "currency": "USD",
    "amount": 100.5,
    "fee": 2.5,
    "card_hash": "hash_1a2b3c4d5e6f",
    "card_type": "credit",
    "exp_month": "01",
    "brand": "visa",
    "bin_number": "424242",
    "cvc": "123"
  },
  "metadata": {
    "campaign_id": "summer_sale_2024",
    "checkout_steps": 3,
    "customer_tier": "premium",
    "referral_source": "google_ads",
    "session_duration": 1200
  }
}

Parameters

Example responses

200 Response

{
  "decision": "ACCEPT",
  "assessment_id": "550e8400-e29b-41d4-a716-446655440000",
  "assessment_type": "WHITELIST",
  "decided_by": {
    "module": "WHITELISTS",
    "priority": 1,
    "decision": "ACCEPT"
  },
  "decision_details": {
    "WHITELISTS": {
      "result": {
        "matches_found": [
          "email"
        ],
        "whitelisted_email": "trusted@company.com",
        "bypass_reason": "trusted_customer"
      }
    }
  }
}

Responses

Get Assessment Details

GET /api/v1/assessments/{assessment_id}

Retrieve detailed information about a specific fraud assessment by its ID.

Parameters

Example responses

200 Response

{
  "assessment_id": "string",
  "assessment_type": "string",
  "charge_id": "string",
  "company_id": "string",
  "decision": "string",
  "decided_by": {},
  "decision_details": {},
  "configuration": {},
  "data": {},
  "snapshot_id": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Responses

List Assessments by Type

GET /api/v1/assessments/type/{assessment_type}

Retrieve a paginated list of assessments filtered by type.

Available assessment types: - CHARGE - Full transaction assessments - EMAIL - Email validation assessments - RULE - Rules-based assessments - BLACKLIST - Blacklist check assessments - WHITELIST - Whitelist check assessments

Results are ordered by creation date (newest first) and support pagination.

Parameters

Example responses

200 Response

{
  "data": [],
  "pagination": {
    "current_page": 1,
    "has_next": true,
    "has_previous": false,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

Responses

Rules

Create fraud detection rule

POST /api/v1/rules/

Create a new custom fraud detection rule using Frauddi's domain-specific language (DSL). Rules are evaluated in real-time during fraud assessments.

Body parameter

{
  "value": "payment.amount > 1000 and customer.email.contains('@gmail.com')",
  "decision": "ACCEPT",
  "expire_at": "2024-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "decision": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

List fraud detection rules

GET /api/v1/rules/

Retrieve a paginated list of all fraud detection rules for your company.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "id": "rule_123456",
      "value": "payment.amount > 1000 and customer.email.contains('@suspicious.com')",
      "decision": "REJECT",
      "expire_at": "2024-12-31T23:59:59Z",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Update fraud detection rule

PUT /api/v1/rules/{rule_id}

Update an existing fraud detection rule. The rule will be validated before applying changes.

Body parameter

{
  "value": "payment.amount > 1000 and customer.email.contains('@gmail.com')",
  "decision": "ACCEPT",
  "expire_at": "2024-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "decision": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Delete fraud detection rule

DELETE /api/v1/rules/{rule_id}

Permanently delete a fraud detection rule. This action cannot be undone.

Parameters

Example responses

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Get fraud detection rule

GET /api/v1/rules/{rule_id}

Retrieve a specific fraud detection rule by its ID.

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "decision": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Simulate fraud detection rules

POST /api/v1/rules/simulate

Test how your fraud detection rules would perform against historical transaction data without affecting live assessments. This endpoint allows you to optimize rule logic and validate effectiveness before deploying to production.

Body parameter

{
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T23:59:59Z",
  "rules": [
    {
      "decision": "REJECT",
      "expire_at": "2024-12-31T23:59:59Z",
      "value": "amount > 500"
    }
  ],
  "include_charge_ids": false
}

Parameters

Example responses

200 Response

{
  "baseline": {},
  "current": {},
  "impact": {
    "acceptance_change": 0,
    "acceptance_change_percentage": 0,
    "declined_change": 0,
    "declined_change_percentage": 0
  },
  "errors": [],
  "total_charges_analyzed": 0,
  "total_rules_evaluated": 0,
  "rule_applications": []
}

Responses

Graph

Get Customer Relationship Graph

GET /api/v1/graph/

Retrieve the relationship graph data for a specific customer showing all connected entities.

This endpoint returns network analysis data including: - Connected customers - Other customers linked through shared attributes - Relationship strength - Confidence scores for connections - Graph nodes - Customer entities with their properties - Graph edges - Relationships between customers with metadata - Visualization data - Optimized for D3.js, vis.js, or Cytoscape libraries

Perfect for fraud ring detection, customer network analysis, and relationship visualization.

Parameters

Example responses

200 Response

{
  "nodes": [
    {
      "id": "CUSTOMER_123",
      "label": "John Doe",
      "email": "john@example.com",
      "risk_score": 0.3,
      "connections": 2
    }
  ],
  "edges": [
    {
      "source": "CUSTOMER_123",
      "target": "CUSTOMER_456",
      "relationship_type": "shared_email",
      "strength": 0.85
    }
  ]
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Add Customer to Graph

POST /api/v1/graph/

Add a new customer to the relationship graph and automatically detect connections.

This endpoint performs intelligent relationship detection based on shared attributes: - Email addresses - Exact and domain-based matching - Phone numbers - Direct number matching - Card numbers - Secure hash-based matching - IP addresses - Geographic and exact IP matching - Device fingerprints - Browser/device identification - Address data - Physical location correlation

The system automatically calculates relationship strength and identifies potential fraud rings.

Body parameter

{
  "customer_id": "CUST_12345",
  "email": "customer@example.com",
  "phone": "+1234567890",
  "card_number": "4111111111111111",
  "merchant_id": "MERCH_001",
  "ip_addresses": [
    "192.168.1.1",
    "10.0.0.1"
  ],
  "device_ids": [
    "device_123",
    "mobile_456"
  ],
  "acceptance": 10,
  "declined": 2,
  "chargeback_fraud": 0,
  "chargeback_authorization": 0,
  "chargeback_processing_error": 0,
  "chargeback_customer_dispute": 0,
  "chargeback_non_receipt": 0,
  "chargeback_cancelled_recurring": 0,
  "chargeback_product_not_received": 0,
  "chargeback_duplicate_processing": 0
}

Parameters

Example responses

201 Response

{
  "customer_id": "CUSTOMER_789",
  "relationships_detected": 3,
  "connected_customers": [
    "CUSTOMER_123",
    "CUSTOMER_456"
  ],
  "risk_indicators": [
    "shared_device",
    "same_ip_range"
  ],
  "graph_updated": true
}

Responses

Get Graph Analytics & Statistics

GET /api/v1/graph/stats

Get comprehensive analytics and statistics for a customer's relationship network.

This endpoint provides deep insights into customer relationships including: - Network metrics - Connection count, cluster size, centrality scores - Risk indicators - Network-based risk patterns and anomalies - Transaction analytics - Aggregated transaction data across the network - Behavioral patterns - Shared behaviors and suspicious activities - Chargeback analysis - Network-wide chargeback rates and patterns

Essential for fraud investigation, risk assessment, and customer profiling with 360° network visibility.

Parameters

Example responses

200 Response

{
  "customer_id": "CUSTOMER_123",
  "network_size": 15,
  "risk_score": 0.75,
  "transaction_count": 42,
  "chargeback_rate": 0.05,
  "connected_customers": 8,
  "suspicious_patterns": [
    "shared_device",
    "velocity_matching"
  ]
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Analytics

Create Custom Aggregation

POST /api/v1/aggregations/

Create a custom aggregation to track specific metrics based on conditions.

What are Custom Aggregations? Custom aggregations allow you to count transactions that meet specific criteria over time. They are NOT fraud detection rules - they create metrics that can be used in rules.

How it works: 1. Define a condition (when to count) 2. Define time periods (1m, 2m, 3m, 4m, 5m) 3. System automatically counts matching transactions 4. Metrics can be used in fraud detection rules

Examples:

📊 High-value transactions from specific countries: json { "name": "high_value_latam", "value": "charge.amount > 1000 and charge.metadata.country in ['MX', 'BR', 'AR']", "periods": [1, 2, 3, 4, 5] } Creates metrics: custom:high_value_latam:count:1m, custom:high_value_latam:count:2m, etc.

💳 Transactions with specific card types: json { "name": "debit_card_transactions", "value": "charge.payment.card_type == 'debit'", "periods": [1, 5] }

🌍 Transactions from high-risk IPs: json { "name": "vpn_transactions", "value": "charge.metadata.is_vpn == true or charge.metadata.is_proxy == true", "periods": [1, 2, 3] }

🎯 Using in fraud rules: After creating the aggregation, use it in a rule: custom:high_value_latam:count:1m > 10

Body parameter

{
  "name": "daily_transactions",
  "value": "card:5m:count > 10",
  "periods": [
    5,
    30,
    60
  ]
}

Parameters

Example responses

200 Response

{
  "id": "agg_123456",
  "name": "high_value_latam",
  "value": "charge.amount > 1000 and charge.metadata.country in ['MX', 'BR', 'AR']",
  "periods": [
    1,
    2,
    3,
    4,
    5
  ],
  "status": "ACTIVE",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Responses

List Custom Aggregations

GET /api/v1/aggregations/

Retrieve a paginated list of all custom aggregations for your company.

Each aggregation includes: - Name - Unique identifier for the aggregation - Condition (value) - The condition that triggers counting - Periods - Time windows being tracked (in minutes) - Status - ACTIVE or INACTIVE - Timestamps - Creation and last update times

Use the metrics from these aggregations in your fraud detection rules.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "id": "agg_123456",
      "name": "Daily Transaction Volume",
      "value": "card:24h:count > 50 and customer:1h:amount_sum > 10000",
      "periods": [
        5,
        30,
        60,
        360
      ],
      "status": "ACTIVE",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Update Custom Aggregation

PUT /api/v1/aggregations/{aggregation_id}

Update an existing custom aggregation configuration.

You can modify: - Condition (value) - Change when to count transactions - Time periods - Add or remove monitoring periods - Name - Update the aggregation identifier - Status - Activate or deactivate

Note: Changes apply to new transactions only. Historical data processing (backfill) will be available in a future version.

Body parameter

{
  "name": "daily_transactions",
  "value": "card:5m:count > 10",
  "periods": [
    5,
    30,
    60
  ]
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "name": "string",
  "value": "string",
  "periods": [
    0
  ],
  "enabled": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "data": {}
}

Responses

Delete Custom Aggregation

DELETE /api/v1/aggregations/{aggregation_id}

Permanently delete a custom aggregation.

⚠️ Important: - This action cannot be undone - Metrics will stop being collected immediately - Any fraud rules using this aggregation's metrics will fail

Parameters

Example responses

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Get Custom Aggregation

GET /api/v1/aggregations/{aggregation_id}

Retrieve a specific custom aggregation by its ID, including its condition, periods, and current status.

Parameters

Example responses

200 Response

{
  "id": "string",
  "name": "string",
  "value": "string",
  "periods": [
    0
  ],
  "enabled": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "data": {}
}

Responses

List Available Fields for Custom Aggregations

GET /api/v1/aggregations/fields

Get the list of available fields that can be used in custom aggregation conditions.

Example conditions: charge.amount > 5000 charge.payment.card_type == "credit" charge.metadata.country in ["US", "CA"]

Example responses

200 Response

{
  "data": {}
}

Responses

Get Field Descriptions

GET /api/v1/aggregations/fields/description

Get detailed descriptions and data types for all fields available in custom aggregations.

Includes: - Field name and path - Data type (string, number, boolean, etc.) - Description and usage examples - Valid operators for the field type

Example responses

200 Response

{
  "data": {}
}

Responses

Get Aggregation Events

GET /api/v1/aggregations/charges/{charge_id}/events

Get all aggregation events triggered for a specific transaction.

Shows which custom aggregations were incremented when this transaction was processed. Useful for debugging and understanding which metrics were affected by a transaction.

Parameters

Example responses

200 Response

{
  "data": [
    {}
  ],
  "pagination": {}
}

Responses

Blacklists

Create blacklist entry

POST /api/v1/blacklists/

Add a value to the blacklist for automated fraud prevention. Accepts customer emails, phone numbers, or payment card hashes. Blacklisted values will automatically trigger fraud alerts in future assessments.

Body parameter

{
  "value": "user@example.com",
  "expire_at": "2024-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

409 Response

{
  "detail": "The blacklist already exists."
}

422 Response

{
  "detail": "The blacklist could not be added."
}

Responses

Response Schema

List blacklist entries

GET /api/v1/blacklists/

Retrieve all blacklist entries with pagination. Returns customer emails, phone numbers, and payment card hashes currently blocked by fraud prevention system.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "id": "bl_123456",
      "value": "fraud@suspicious.com",
      "type": "email",
      "reason": "Multiple failed transactions",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Update blacklist entry

PUT /api/v1/blacklists/{blacklist_id}

Modify an existing blacklist entry. Updates the value (email, phone number, or card hash) and metadata while preserving the entry's fraud prevention status.

Body parameter

{
  "value": "user@example.com",
  "expire_at": "2024-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

404 Response

{
  "detail": "The blacklist does not exist."
}

Responses

Response Schema

Delete blacklist entry

DELETE /api/v1/blacklists/{blacklist_id}

Remove a value from the blacklist. Deleted entries (email, phone number, or card hash) will no longer trigger fraud alerts in future assessments.

Parameters

Example responses

404 Response

{
  "detail": "The blacklist does not exist."
}

422 Response

{
  "detail": "The blacklist could not be deleted."
}

Responses

Response Schema

Retrieve blacklist entry

GET /api/v1/blacklists/{blacklist_id}

Get details of a specific blacklist entry including its value (email, phone number, or card hash), type, and metadata.

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

404 Response

{
  "detail": "The blacklist does not exist."
}

Responses

Response Schema

Whitelists

Create whitelist entry

POST /api/v1/whitelists/

Add a value to the whitelist for fraud prevention bypass. Accepts customer emails, phone numbers, or payment card hashes. Whitelisted values will automatically be excluded from fraud alerts in future assessments.

Body parameter

{
  "value": "user@example.com",
  "expire_at": "2025-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

409 Response

{
  "detail": "The whitelist already exists."
}

422 Response

{
  "detail": "The whitelist could not be added."
}

Responses

Response Schema

List whitelist entries

GET /api/v1/whitelists/

Retrieve all whitelist entries with pagination. Returns customer emails, phone numbers, and payment card hashes currently excluded from fraud prevention system.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "id": "wl_123456",
      "value": "trusted@company.com",
      "type": "email",
      "reason": "VIP customer",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

Update whitelist entry

PUT /api/v1/whitelists/{whitelist_id}

Modify an existing whitelist entry. Updates the value (email, phone number, or card hash) and metadata while preserving the entry's fraud prevention bypass status.

Body parameter

{
  "value": "user@example.com",
  "expire_at": "2025-12-31T23:59:59Z"
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Delete whitelist entry

DELETE /api/v1/whitelists/{whitelist_id}

Remove a value from the whitelist. Deleted entries (email, phone number, or card hash) will no longer be excluded from fraud alerts in future assessments.

Parameters

Responses

Retrieve whitelist entry

GET /api/v1/whitelists/{whitelist_id}

Get details of a specific whitelist entry including its value (email, phone number, or card hash), type, and metadata.

Parameters

Example responses

200 Response

{
  "id": "string",
  "value": "string",
  "enabled": true,
  "expire_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Snapshots

Create data snapshot

POST /api/v1/snapshots/

Create a backup snapshot of specified data collections. Snapshot creation runs asynchronously in the background.

Body parameter

{
  "description": "Pre-deployment snapshot",
  "collections": [
    "RULES",
    "BLACKLISTS"
  ],
  "drop_existing": false
}

Parameters

Example responses

200 Response

{
  "id": "string",
  "collections": [
    "string"
  ],
  "size_bytes": 0,
  "status": "string",
  "compressed": false,
  "description": "string",
  "backup_path": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Responses

List snapshots

GET /api/v1/snapshots/

Retrieve all snapshots with pagination. Returns snapshot history including creation dates, status, and collection information.

Parameters

Example responses

200 Response

{
  "data": [
    {}
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

Responses

Retrieve snapshot details

GET /api/v1/snapshots/{snapshot_id}

Get detailed information about a specific snapshot including its status, creation date, and collections included.

Parameters

Example responses

200 Response

{
  "id": "string",
  "collections": [
    "string"
  ],
  "size_bytes": 0,
  "status": "string",
  "compressed": false,
  "description": "string",
  "backup_path": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

Responses

Delete snapshot

DELETE /api/v1/snapshots/{snapshot_id}

Permanently delete a snapshot and all its associated data. This action cannot be undone.

Parameters

Responses

Get snapshot metadata

GET /api/v1/snapshots/{snapshot_id}/metadata

Retrieve detailed metadata about a snapshot including collection statistics, data counts, and snapshot integrity information.

Parameters

Example responses

200 Response

{
  "data": {}
}

Responses

Restore snapshot

POST /api/v1/snapshots/{snapshot_id}/restore

Restore data from a snapshot to specified collections. Restoration runs asynchronously in the background and may overwrite existing data.

Body parameter

{
  "description": "Pre-deployment snapshot",
  "collections": [
    "RULES",
    "BLACKLISTS"
  ],
  "drop_existing": false
}

Parameters

Example responses

200 Response

{
  "restore_id": "string",
  "snapshot_id": "string",
  "company_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "collections": [
    "string"
  ],
  "description": "",
  "status": "string",
  "drop_existing": false
}

Responses

List restore operations

GET /api/v1/snapshots/{snapshot_id}/restore

Retrieve all restore operations for a specific snapshot with pagination. Shows restore history including status and timestamps.

Parameters

Example responses

200 Response

{
  "data": [
    {}
  ],
  "pagination": {
    "current_page": 1,
    "has_next": false,
    "has_previous": true,
    "last_page": 1,
    "next_page": 2,
    "page_size": 20
  }
}

Responses

Get restore operation details

GET /api/v1/snapshots/{snapshot_id}/restore/{snapshot_restore_id}

Retrieve detailed information about a specific restore operation including status, progress, and any errors encountered.

Parameters

Example responses

200 Response

{
  "restore_id": "string",
  "snapshot_id": "string",
  "company_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "collections": [
    "string"
  ],
  "description": "",
  "status": "string",
  "drop_existing": false
}

Responses

Compare snapshots

POST /api/v1/snapshots/compare

Compare two snapshots to identify differences in fraud detection module data, providing detailed change analysis for audit and rollback purposes.

Body parameter

{
  "baseline_snapshot_id": "snapshot_20240101_baseline",
  "current_snapshot_id": "snapshot_20240201_current"
}

Parameters

Example responses

200 Response

{
  "rules": {},
  "whitelists": {},
  "blacklists": {}
}

Responses

Anomalies

Detect anomalies with filters

POST /api/v1/anomalies/tree

Execute anomaly detection to identify unusual patterns in transaction data with configurable filtering.

Body parameter

{
  "fields": [
    "payment.amount"
  ],
  "query": {
    "status": "completed"
  },
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T23:59:59Z",
  "top": 5,
  "min_value": 10,
  "min_percentage": 5
}

Parameters

Example responses

200 Response

{
  "total_records": 0,
  "fields": [
    "string"
  ],
  "patterns": {},
  "params": {},
  "query": {}
}

Responses

Auto-discover anomaly patterns

POST /api/v1/anomalies/discover

Automatically discover the most important concentration patterns in your data without specifying fields in advance.

Body parameter

{
  "query": {
    "status": "completed"
  },
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T23:59:59Z",
  "max_fields": 2,
  "min_percentage": 1,
  "limit": 10
}

Parameters

Example responses

200 Response

{
  "total_records": 0,
  "fields": [
    {}
  ],
  "patterns": [
    {}
  ],
  "params": {},
  "query": {}
}

Responses

Find concentration patterns

POST /api/v1/anomalies/find

Find where your data concentrates across specified fields. Includes configurable filtering options and depth control.

Body parameter

{
  "fields": [
    "payment.amount"
  ],
  "query": {
    "status": "completed"
  },
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T23:59:59Z",
  "min_percentage": 1,
  "max_depth": 2,
  "contains": "visa",
  "min_count": 10,
  "sort_by": "percentage",
  "limit": 20
}

Parameters

Example responses

200 Response

{
  "total_records": 0,
  "fields": [
    "string"
  ],
  "patterns": [
    {}
  ],
  "params": {},
  "query": {}
}

Responses

Perform statistical analysis

POST /api/v1/anomalies/analyze

Conduct deep statistical analysis on data patterns. Provides confidence scores, statistical significance, and actionable insights for each pattern.

Body parameter

{
  "fields": [
    "payment.amount"
  ],
  "query": {
    "status": "completed"
  },
  "from_date": "2024-01-01T00:00:00Z",
  "to_date": "2024-01-31T23:59:59Z",
  "min_percentage": 5
}

Parameters

Example responses

200 Response

{
  "total_records": 0,
  "fields": [
    "string"
  ],
  "patterns": [
    {}
  ],
  "params": {},
  "query": {},
  "insights": {},
  "statistics": {}
}

Responses

Compare data between time periods

POST /api/v1/anomalies/compare

Compare data patterns between current and baseline periods. Detects changes, new patterns, and disappeared patterns for A/B testing and trend analysis.

Body parameter

{
  "fields": [
    "payment.amount"
  ],
  "current_from_date": "2024-02-01T00:00:00Z",
  "current_to_date": "2024-02-29T23:59:59Z",
  "baseline_from_date": "2024-01-01T00:00:00Z",
  "baseline_to_date": "2024-01-31T23:59:59Z",
  "query": {
    "status": "completed"
  },
  "change_threshold": 0.1,
  "statistical_significance": true
}

Parameters

Example responses

200 Response

{
  "current_records": 0,
  "baseline_records": 0,
  "fields": [
    "string"
  ],
  "changes": [
    {}
  ],
  "added_patterns": [
    {}
  ],
  "removed_patterns": [
    {}
  ],
  "statistics": {},
  "params": {},
  "query": {}
}

Responses

Get available analysis fields

GET /api/v1/anomalies/fields

Retrieve categorized list of fields available for anomaly analysis including customer, payment, and charge fields.

Example responses

200 Response

{
  "customer_fields": [
    "string"
  ],
  "payment_fields": [
    "string"
  ],
  "charge_fields": [
    "string"
  ]
}

Responses

Charges

Retrieve charge details

GET /api/v1/charges/{charge_id}

Get detailed information about a specific charge including transaction data, customer information, and assessment results.

Parameters

Example responses

200 Response

{
  "charge_id": "string",
  "status": "pending",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "customer": {
    "full_name": "string",
    "phone_number": "string",
    "email": "string",
    "ip_address": "string",
    "fingerprint": "string"
  },
  "payment": {
    "currency": "USD",
    "amount": 0,
    "fee": 0,
    "card_hash": "string",
    "card_type": "string",
    "exp_month": "string",
    "brand": "string",
    "bin_number": "string",
    "cvc": "string"
  }
}