API Documentation

Getting Started

Welcome to the WebFunctions API documentation. Follow these steps to integrate our 200+ APIs into your application.

curl -X POST https://api.webfunctions.net/v1/email/validate \
  -H "Authorization: Bearer wf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Request Header

API Key Format

API keys are prefixed with wf_ followed by 48 alphanumeric characters.

Managing API Keys

• Generate multiple keys for different environments (development, staging, production)
• Rotate keys regularly for enhanced security
• Revoke compromised keys immediately from your dashboard
• Set IP whitelist restrictions for additional security (Enterprise plans)

Credits & Usage

WebFunctions uses a credit-based billing system. Each API call consumes credits based on the endpoint complexity.

Credit Consumption

Checking Your Balance

Query your current credit balance and usage:

GET /v1/account/credits

// Response
{
  "credits_remaining": 847523,
  "credits_used": 152477,
  "credits_total": 1000000,
  "period_start": "2026-01-01T00:00:00Z",
  "period_end": "2026-01-31T23:59:59Z",
  "plan": "Starter"
}

Usage Headers

Every API response includes credit usage information in headers:

• X-Credits-Used - Credits consumed by this request
• X-Credits-Remaining - Credits remaining in your account
• X-Credits-Reset - Unix timestamp when credits reset

Rate Limits

Rate limits are applied per API key to ensure service stability and fair usage across all customers.

Limits by Plan

Rate Limit Headers

Each response includes headers to help you track your rate limit status:

• X-RateLimit-Limit - Maximum requests per second
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when the window resets

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

HTTP Status Codes

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The email address format is invalid",
    "param": "email",
    "doc_url": "https://webfunctions.net/docs#email-validation"
  },
  "request_id": "req_abc123xyz"
}

Webhooks

Receive real-time notifications when events occur. Configure webhook endpoints in your dashboard.

Supported Events

• bulk.completed - Bulk operation finished processing
• credits.low - Credits dropped below threshold (50%, 20%, 10%)
• credits.depleted - All credits consumed
• api_key.revoked - An API key was revoked

Webhook Payload

{
  "event": "bulk.completed",
  "timestamp": "2026-01-19T12:34:56Z",
  "data": {
    "job_id": "job_abc123",
    "total_records": 10000,
    "successful": 9850,
    "failed": 150,
    "download_url": "https://..."
  },
  "signature": "sha256=..."
}

Verifying Signatures

Always verify webhook signatures to ensure authenticity:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Email Validation

1 credit per request

Validate email addresses for format, DNS records, disposable status, and deliverability.

Endpoint

Request

{
  "email": "user@example.com",
  "check_deliverability": true  // Optional, uses 1 additional credit
}

Response

{
  "email": "user@example.com",
  "valid": true,
  "format_valid": true,
  "mx_found": true,
  "mx_records": ["mx1.example.com", "mx2.example.com"],
  "disposable": false,
  "role_based": false,
  "free_provider": false,
  "deliverable": true,
  "catch_all": false,
  "score": 95,
  "suggestion": null
}

Response Fields

Phone Validation

1-2 credits per request

Validate phone numbers for format, carrier information, and line type.

Endpoint

Request

{
  "phone": "+14155551234",
  "country_code": "US"  // Optional, for national format numbers
}

Response

{
  "valid": true,
  "phone_number": "+14155551234",
  "national_format": "(415) 555-1234",
  "international_format": "+1 415-555-1234",
  "country_code": "US",
  "country_name": "United States",
  "carrier": "Verizon Wireless",
  "line_type": "mobile",
  "is_ported": false
}

IP Geolocation

2 credits per request

Get detailed location and network information for any IP address.

Endpoint

Response

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "continent": "North America",
  "continent_code": "NA",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "region_code": "CA",
  "city": "Mountain View",
  "zip": "94035",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "utc_offset": "-08:00",
  "currency": "USD",
  "isp": "Google LLC",
  "organization": "Google Public DNS",
  "asn": "AS15169",
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "is_datacenter": true,
  "threat_score": 0
}

Address Verification

2 credits per request

Validate and standardize postal addresses with USPS and international support.

Endpoint

Request

{
  "street": "1600 Amphitheatre Parkway",
  "city": "Mountain View",
  "state": "CA",
  "zip": "94043",
  "country": "US"
}

Response

{
  "valid": true,
  "deliverable": true,
  "standardized": {
    "street": "1600 AMPHITHEATRE PKWY",
    "city": "MOUNTAIN VIEW",
    "state": "CA",
    "zip": "94043-1351",
    "country": "US"
  },
  "components": {
    "primary_number": "1600",
    "street_name": "AMPHITHEATRE",
    "street_suffix": "PKWY",
    "city_name": "MOUNTAIN VIEW",
    "state_abbreviation": "CA",
    "zipcode": "94043",
    "plus4_code": "1351"
  },
  "metadata": {
    "latitude": 37.4224764,
    "longitude": -122.0842499,
    "time_zone": "America/Los_Angeles",
    "address_type": "commercial"
  }
}

Identity Verification

5 credits per request

Verify identity information against authoritative data sources.

Endpoint

Request

{
  "first_name": "John",
  "last_name": "Smith",
  "date_of_birth": "1990-01-15",
  "ssn_last4": "1234",  // Optional
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210"
  }
}

Response

{
  "verified": true,
  "confidence_score": 92,
  "checks": {
    "name_match": true,
    "dob_match": true,
    "ssn_match": true,
    "address_match": true
  },
  "alerts": [],
  "sources_checked": 3
}

Fraud Detection

5 credits per request

Real-time fraud scoring and risk assessment for transactions and signups.

Endpoint

Request

{
  "email": "user@example.com",
  "ip_address": "192.168.1.1",
  "phone": "+14155551234",
  "transaction": {
    "amount": 99.99,
    "currency": "USD",
    "type": "purchase"
  },
  "device": {
    "user_agent": "Mozilla/5.0...",
    "fingerprint": "abc123"
  }
}

Response

{
  "risk_score": 15,
  "risk_level": "low",
  "recommendation": "approve",
  "signals": {
    "email_age_days": 1825,
    "email_disposable": false,
    "ip_proxy": false,
    "ip_country_match": true,
    "device_fingerprint_seen": true,
    "velocity_check": "pass"
  },
  "rules_triggered": []
}

SDKs & Libraries

Official SDKs are available for seamless integration in your preferred language.

# ~/.ssh/config for TSC tunnel
Host wf-tsc-tunnel
    HostName tsc-tunnel.webfunctions.net
    Port 22022
    User wf_tsc_[YOUR_ORG_ID]
    IdentityFile ~/.ssh/webfunctions_tsc_ed25519
    LocalForward 8443 api-internal.webfunctions.net:443
    ServerAliveInterval 60
    ServerAliveCountMax 3
    StrictHostKeyChecking yes
    UserKnownHostsFile ~/.ssh/wf_known_hosts

# Start the SSH tunnel
ssh -N -f wf-tsc-tunnel

# Verify tunnel is active
curl -s https://localhost:8443/v1/health \
  -H "Authorization: Bearer wf_tsc_your_api_key" \
  --cacert /path/to/webfunctions-tsc-ca.crt

# Response
{"status": "operational", "tunnel": "tsc-secured", "encryption": "AES-256-GCM"}

# Python TSC Example
from webfunctions import WebFunctionsClient, TSCTunnel

# Initialize TSC tunnel manager
tunnel = TSCTunnel(
    key_path="~/.ssh/webfunctions_tsc_ed25519",
    org_id="YOUR_ORG_ID",
    ca_cert="/path/to/webfunctions-tsc-ca.crt"
)

# Start secure tunnel
tunnel.connect()

# Initialize client with tunnel
client = WebFunctionsClient(
    api_key="wf_tsc_your_api_key",
    base_url="https://localhost:8443",
    tsc_mode=True,
    verify_ssl=tunnel.ca_cert
)

# Make TSC-secured API call
result = client.identity.verify_classified(
    subject_id="REDACTED",
    clearance_level="TSC",
    audit_log=True
)

# Always close tunnel when done
tunnel.disconnect()

// Node.js TSC Example
const { WebFunctionsClient, TSCTunnel } = require('@webfunctions/sdk-tsc');

async function secureLookup() {
    // Initialize TSC tunnel
    const tunnel = new TSCTunnel({
        keyPath: '~/.ssh/webfunctions_tsc_ed25519',
        orgId: 'YOUR_ORG_ID',
        caCert: '/path/to/webfunctions-tsc-ca.crt'
    });

    await tunnel.connect();

    const client = new WebFunctionsClient({
        apiKey: 'wf_tsc_your_api_key',
        baseUrl: 'https://localhost:8443',
        tscMode: true,
        caCert: tunnel.caCert
    });

    try {
        const result = await client.identity.verifyClassified({
            subjectId: 'REDACTED',
            clearanceLevel: 'TSC',
            auditLog: true
        });
        console.log(result);
    } finally {
        await tunnel.disconnect();
    }
}

secureLookup();

Don't see your language? The REST API works with any HTTP client. Request an SDK

Postman Collection

Import our Postman collection to quickly explore and test all API endpoints.

Changelog

Recent updates and changes to the WebFunctions API.