WinFwins API Documentation

Overview

Welcome to the WinFwins Affiliate SDK API documentation. This API allows you to integrate lead generation and management capabilities into your applications.

Key Features

• Create and submit leads to the platform
• Search and retrieve lead information with flexible filtering
• Track lead status and deposit information
• Support for UTM parameters and custom tracking IDs

Getting Started

To use the API, you'll need:

1. API Key - Contact your manager to obtain your API key
2. Affiliate Code (affc) - Your unique affiliate identifier
3. Hub Code (bxc) - Your assigned hub identifier
4. Vertical Code (vtc) - The vertical/category identifier

Authentication

All API requests must include an API key in the request headers.

Header Format

x-api-key: your-api-key-here

Example Request with Authentication

GET /api/external/integration/lead HTTP/1.1
Host: api.winfx.live
x-api-key: 6aca18d1-10eb-4e2f-8f1a-da0a74e52199
Content-Type: application/json

Create Lead

Submit a new lead to the WinFwins platform. This endpoint validates the lead information and returns a redirect URL for the lead.

Request Headers

Request Body Parameters

Profile Object

Example Request

{
    "affc": "AFF-00000000",
    "bxc": "BX-00000000",
    "vtc": "VT-HP8XSRMKVS6E7",
    "profile": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "password": "SecurePass123",
        "phone": "13439105691"
    },
    "ip": "209.151.4.139",
    "funnel": "premium-funnel",
    "landingURL": "https://example.com/landing",
    "geo": "CA",
    "lang": "en",
    "landingLang": "en",
    "utmSource": "FB",
    "utmMedium": "CPL",
    "utmCampaign": "summer-2024",
    "utmId": "304304903940",
    "subId": "click-id-12345"
}

Response Examples

{
    "success": true,
    "redirectUrl": "https://google.com",
    "leadId": "aa99ee7b-c52b-43d0-98ba-601e5d864681"
}

{
    "message": "Account not authorized.",
    "code": "acNA",
    "statusCode": 401
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "Hub not found."
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "Vertical template not found."
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "Hub is not sendable."
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "No hubs available for this lead."
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "Lead with same profile data recently registered."
}

{
    "success": false,
    "redirectUrl": null,
    "leadId": null,
    "error": "Lead with same IP recently registered."
}

Search Leads

Retrieve leads based on date range and pagination parameters. This endpoint allows you to fetch lead data for reporting and tracking purposes.

Request Headers

Query Parameters

Example Request

curl --location 'https://api.winfx.live/api/external/integration/lead?from=2025-05-21&to=2025-05-23&take=250&skip=0' \
--header 'x-api-key: a4f8c9d2-3b7e-4a1f-9e2d-6c5b8a7f3e1d'

Response Example

{
    "count": 4,
    "rows": [
        {
            "id": "4d1dafec-e9b6-4281-b36d-6e8b51de57c0",
            "registration": {
                "status": "sent",
                "rawStatus": "Callback"
            },
            "profile": {
                "email": "test_447350483104@test.com",
                "lastName": "McCullough",
                "firstName": "Misty"
            },
            "ip": "195.88.156.200",
            "geo": "GB",
            "utmSource": "3",
            "utmMedium": "4",
            "utmCampaign": "5",
            "utmId": "2",
            "subId": "sub-O6MfExa",
            "subId_a": null,
            "subId_b": null,
            "subId_c": null,
            "subId_d": null,
            "subId_e": null,
            "subId_f": null,
            "isDeposited": false,
            "createdAt": "2025-05-21T22:56:14.446Z",
            "depositedAt": null
        },
        {
            "id": "caed02ef-1563-4ddb-9ca2-da940bd871df",
            "registration": {
                "status": "sent",
                "rawStatus": "Callback"
            },
            "profile": {
                "email": "test_447350488078@test.com",
                "lastName": "Swaniawski",
                "firstName": "Lolita"
            },
            "ip": "193.237.140.105",
            "geo": "GB",
            "utmSource": "3",
            "utmMedium": "4",
            "utmCampaign": "5",
            "utmId": "2",
            "subId": "sub-gWZ0gYU",
            "subId_a": null,
            "subId_b": null,
            "subId_c": null,
            "subId_d": null,
            "subId_e": null,
            "subId_f": null,
            "isDeposited": false,
            "createdAt": "2025-05-21T22:41:38.872Z",
            "depositedAt": null
        },
        {
            "id": "abc1905d-c08f-4d43-be87-3910dc0bd7fe",
            "registration": {
                "status": "sent",
                "rawStatus": "Callback"
            },
            "profile": {
                "email": "test_447350488171@test.com",
                "lastName": "Kiehn-Pollich",
                "firstName": "Jo"
            },
            "ip": "185.171.201.217",
            "geo": "GB",
            "utmSource": null,
            "utmMedium": null,
            "utmCampaign": null,
            "utmId": null,
            "subId": "sub-Jp7IeOD",
            "subId_a": null,
            "subId_b": null,
            "subId_c": null,
            "subId_d": null,
            "subId_e": null,
            "subId_f": null,
            "isDeposited": false,
            "createdAt": "2025-05-21T22:41:15.310Z",
            "depositedAt": null
        },
        {
            "id": "a7b39b2b-f5b8-4320-9ba4-039fb3452272",
            "registration": {
                "status": "sent",
                "rawStatus": "Callback"
            },
            "profile": {
                "email": "test_447350481848@test.com",
                "lastName": "White",
                "firstName": "Melody"
            },
            "ip": "196.242.89.8",
            "geo": "GB",
            "utmSource": null,
            "utmMedium": null,
            "utmCampaign": null,
            "utmId": null,
            "subId": "sub-8R8cJFo",
            "subId_a": null,
            "subId_b": null,
            "subId_c": null,
            "subId_d": null,
            "subId_e": null,
            "subId_f": null,
            "isDeposited": false,
            "createdAt": "2025-05-21T22:40:52.728Z",
            "depositedAt": null
        }
    ]
}

Response Fields

Lead Status Values

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in the response body.

Common Status Codes

Error Response Examples

{
    "message": "Account not authorized.",
    "code": "acNA",
    "statusCode": 401
}

Handling Errors in Your Code

Example error handling in JavaScript:

async function createLead(leadData) {
    try {
        const response = await fetch('https://api.winfx.live/api/external/integration/lead', {
            method: 'POST',
            headers: {
                'x-api-key': 'your-api-key',
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(leadData)
        });

        const result = await response.json();

        if (result.success) {
            // Lead created successfully
            window.location.href = result.redirectUrl;
        } else {
            // Handle error
            console.error('Lead creation failed:', result.error);
            alert('Failed to create lead: ' + result.error);
        }
    } catch (error) {
        console.error('Network error:', error);
        alert('Network error occurred. Please try again.');
    }
}

Best Practices

Security

• Never expose your API key in client-side code or public repositories
• Use environment variables to store sensitive credentials
• Implement rate limiting on your end to prevent abuse
• Use HTTPS for all API requests

Performance

• Use pagination when fetching large numbers of leads
• Implement caching for frequently accessed data

Data Quality

• Validate email addresses before submission
• Ensure IP addresses are accurate and not proxied
• Use proper country and language codes
• Include UTM parameters for better tracking
• Populate subId fields for accurate conversion tracking

Monitoring

• Log all API requests and responses
• Set up alerts for unusual patterns or high error rates
• Track lead conversion and deposit rates

Support

If you need assistance with the API or have questions about integration:

Common Support Requests

• Requesting API keys and credentials
• Obtaining affiliate, hub, and vertical codes
• Understanding error messages and troubleshooting
• Checking hub availability and cap limits
• Reviewing lead quality and conversion rates