Loading...

API Documentation

Complete reference for the Fraud Check API

Try API

Contents

Getting Started

Welcome to the Fraud Check API! This powerful API helps you validate and verify various types of data including emails, domains, IP addresses, and phone numbers.

Quick Start

  1. Get your API key from the API Keys page
  2. Make your first request to the /api/query endpoint
  3. Review the response and integrate into your application

Base URL

https://api.fraudcheck.com

Authentication

Authentication is required for all API endpoints. Include your API key in the request header:

Authentication Example
BASH
curl -X POST "https://api.fraudcheck.com/api/query" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"type": "email", "value": "test@example.com"}'

Security Note

Never expose your API key in client-side code. Always make requests from your server.

API Reference

POST/api/query

Perform fraud checks on various data types including emails, domains, IPs, and phone numbers.

Request Body

Query Request
JSON
{
  "type": "email",
  "value": "test@example.com",
  "options": {
    "detailed": true
  }
}

Response

Query Response
JSON
{
  "success": true,
  "data": {
    "type": "email",
    "value": "test@example.com",
    "valid": true,
    "risk_score": 0.2,
    "checks": {
      "domain_valid": true,
      "mx_record": true,
      "disposable": false,
      "blacklisted": false
    }
  },
  "metadata": {
    "request_id": "req_123456",
    "timestamp": "2023-12-01T10:00:00Z"
  }
}

Parameters

Parameter Type Required Description
typestringRequiredThe type of data to check (email, domain, ip, phone)
valuestringRequiredThe value to check
optionsobjectOptionalAdditional options for the check
metadataobjectOptionalCustom metadata to include in the response
GET/api/stats

Get usage statistics for your API key.

Request

Stats Request
BASH
curl -X GET "https://api.fraudcheck.com/api/stats" \
  -H "X-API-Key: your-api-key-here"

Response

Stats Response
JSON
{
  "success": true,
  "data": {
    "total_requests": 1250,
    "successful_requests": 1200,
    "failed_requests": 50,
    "rate_limit": {
      "limit": 1000,
      "remaining": 850,
      "reset": 1701432000
    }
  }
}

Supported Data Types

Email Address

Validate and check email addresses for fraud indicators

Example: user@example.com
Validation: RFC 5322 compliant format
Checks: Domain validation, MX record check, Disposable email detection, Blacklist check

Domain Name

Check domain reputation and validity

Example: example.com
Validation: Valid domain format
Checks: DNS resolution, Age verification, Reputation scoring, Blacklist check

IP Address

Analyze IP addresses for suspicious activity

Example: 192.168.1.1
Validation: IPv4 or IPv6 format
Checks: Geolocation, VPN detection, Tor exit node check, Reputation scoring

Phone Number

Validate phone numbers and detect fraud patterns

Example: +1234567890
Validation: E.164 international format
Checks: Number validity, Carrier lookup, Line type detection, Fraud scoring

Code Examples

Basic Email Check

Basic Email Check
JAVASCRIPT
const FraudCheck = require('fraudcheck-js');

const client = new FraudCheck('your-api-key');

async function checkEmail(email) {
  try {
    const result = await client.query({
      type: 'email',
      value: email
    });
    
    console.log('Result:', result);
    return result;
  } catch (error) {
    console.error('Error:', error);
  }
}

checkEmail('test@example.com');

Batch Processing

Batch Processing
JAVASCRIPT
const emails = ['user1@example.com', 'user2@example.com'];

const results = await Promise.all(
  emails.map(email => 
    client.query({ type: 'email', value: email })
  )
);

console.log('Batch results:', results);

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

400

Bad Request

The request was invalid or missing required parameters.

400 Error Example
JSON
{
  "error": "Bad Request",
  "message": "Missing required field: type",
  "code": "MISSING_FIELD"
}
401

Unauthorized

Authentication failed or API key is invalid.

401 Error Example
JSON
{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}
429

Rate Limit Exceeded

Too many requests were made within the allowed time frame.

429 Error Example
JSON
{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests, please try again later",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}
500

Internal Server Error

An unexpected error occurred on the server.

500 Error Example
JSON
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}

Rate Limits

API requests are subject to rate limits to ensure fair usage and system stability.

Rate Limit Headers

X-RateLimit-Limit: Requests per hour
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset time (Unix timestamp)

Rate Limit Exceeded

When rate limits are exceeded, you'll receive a 429 status code. Implement exponential backoff in your retry logic.

SDKs & Libraries

JavaScript/Node.js

Official JavaScript SDK

Install: npm install fraudcheck-js
Documentation

Python

Official Python SDK

Install: pip install fraudcheck-python
Documentation

PHP

Official PHP SDK

Install: composer require fraudcheck/php-sdk
Documentation

Go

Official Go SDK

Install: go get github.com/fraudcheck/go-sdk
Documentation

Ruby

Official Ruby SDK

Install: gem install fraudcheck-ruby
Documentation

Java

Official Java SDK

Install: implementation "com.fraudcheck:java-sdk:1.0"
Documentation