Affiliate APIPrivate & Confidential

API Integration Documentation

Integration Reference • June 2026

Base URL: https://api.willistudio.io

Your API Credentials

API Token

YOUR_API_KEY_HERE

⚠️ All requests must include a Bearer Token in the Authorization header. For enhanced security, you can request IP whitelisting for all API actions — contact support to configure this.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Missing Token

{"success": false, "message": "API key is required"}

Invalid Token

{"success": false, "message": "Invalid API key"}

Retrieve Your Clients

Get a paginated, filterable list of clients associated with your affiliate account.

GEThttps://api.willistudio.io/api/v1/affiliates/clients

Query Parameters

Parameter	Type	Default	Description
`page`	integer	0	Records to skip (pagination offset)
`limit`	integer	100	Max records returned (max 500)
`search`	string	—	Search by ID, name, email, phone, or status
`created_at_start`	date	—	Registered on or after this date (YYYY-MM-DD)
`created_at_end`	date	—	Registered on or before this date (YYYY-MM-DD)
`ftd_date_start`	date	—	First deposit on or after (YYYY-MM-DD)
`ftd_date_end`	date	—	First deposit on or before (YYYY-MM-DD)
`country_ids`	UUID	—	Filter by country UUID
`customer_status_ids`	UUID	—	Filter by customer status UUID
`brand_ids`	UUID	—	Filter by brand UUID
`sort_by`	string	created_at	Sort field: created_at, first_name, last_name, email
`sort_order`	string	desc	Sort direction: asc or desc

Example Request

curl -X GET "https://api.willistudio.io/api/v1/affiliates/clients?page=0&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total": 100,
  "page": 0,
  "limit": 100,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+491234567890",
      "country_name": "Germany",
      "country_code": "DE",
      "registration_ip": "192.168.1.1",
      "status": "New",
      "brand_name": "Default Brand",
      "created_at": "2026-06-15T10:30:00.000Z",
      "ftd_date": null,
      "balance_currency": "USD",
      "balance_currency_value": "0",
      "buyer_lead_id": 192,
      "buyer_lead_status": "new"
    }
  ]
}

Lead Status Values

The buyer_lead_status field indicates the current status of your lead. Possible values:

Status	Description
`null`	Lead has not been forwarded yet or is pending
`new`	Lead has been received and is awaiting processing
`No answer`	Lead did not answer the call
`No potential`	Lead has no potential for conversion
`Wrong number`	Phone number is incorrect or invalid
`Hung Up`	Lead hung up during the call
`Call again`	Lead needs to be called again
`Call back`	Lead requested a callback
`Deposit`	Lead has made a deposit

🔄 How to Track Lead Status

After you submit a lead, the status is automatically updated every 3 minutes. To retrieve the latest status, simply call the GET /v1/affiliates/clients endpoint periodically.

✅ Recommended approach: Set up a polling interval on your side (e.g., every 3–5 minutes) to fetch updated lead statuses.

✅ Use the buyer_lead_status field to track each lead's progress.

✅ Use the buyer_lead_id field to cross-reference leads with the buyer system.

Example: Poll for Status Updates

# Fetch your leads and check their current status
curl -X GET "https://api.willistudio.io/api/v1/affiliates/clients?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter response by buyer_lead_status to find updated leads
# Example response fields per lead:
#   "buyer_lead_id": 218
#   "buyer_lead_status": "No answer"  ← updated by the buyer team

💡 Tip: If buyer_lead_status is null, the lead is still being processed. Once it changes to a value like new, contacted, or ftd, the buyer team has started working on it.

Create a New Lead

POSThttps://api.willistudio.io/api/v1/affiliates/leads

Required Fields

Field	Type	Description
`brand_id`	UUID	Brand to assign the lead (use /by-brands to list)
`first_name`	string	Client first name
`last_name`	string	Client last name
`email`	string	Client email address (must be unique)
`phone`	string	Client phone number
`country_id`	UUID	Country UUID (use /countries to list)

Optional Fields

Field	Type	Description
`password`	string	Optional. Omit or leave empty to auto-generate
`country_code`	string	ISO country code (alternative to country_id)
`source_id`	integer	Business source ID
`marketing_metadata`	string	Additional marketing metadata
`registration_ip`	string	Client IP at point of registration
`balance_currency`	string	Base currency (e.g. USD, EUR)

Example Request

curl -X POST "https://api.willistudio.io/api/v1/affiliates/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "BRAND_UUID",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+491234567890",
    "country_id": "COUNTRY_UUID",
    "registration_ip": "192.168.1.1",
    "marketing_metadata": "Campaign-Front-1"
  }'

Success Response

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "affiliate_id": "YOUR_AFFILIATE_UUID",
    "brand_id": "BRAND_UUID",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+491234567890",
    "country_id": "COUNTRY_UUID",
    "created_at": "2026-06-24T14:30:00.000Z"
  }
}

Error Responses

Missing Required Fields

{"success": false, "message": "Zorunlu alanlar: brand_id, first_name, last_name, email, phone, country_id"}

Duplicate Email

{"success": false, "message": "This email is already registered"}

Auxiliary Endpoints

Reference endpoints for populating integration parameters.

Get Available Brands

GEThttps://api.willistudio.io/api/v1/affiliates/by-brands

curl -X GET "https://api.willistudio.io/api/v1/affiliates/by-brands" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [{ "id": "uuid-...", "name": "Default Brand" }] }

Get Countries

GEThttps://api.willistudio.io/api/v1/affiliates/countries

curl -X GET "https://api.willistudio.io/api/v1/affiliates/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [{ "id": "uuid-...", "name": "Turkey", "code": "TR" }] }

Get Customer Statuses

GEThttps://api.willistudio.io/api/v1/affiliates/customer-statuses

curl -X GET "https://api.willistudio.io/api/v1/affiliates/customer-statuses" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [{ "id": "uuid-...", "name": "New" }, { "id": "uuid-...", "name": "Converted" }] }

Get Available Currencies

GEThttps://api.willistudio.io/api/v1/affiliates/available-currencies

curl -X GET "https://api.willistudio.io/api/v1/affiliates/available-currencies" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [{ "id": "uuid-...", "code": "USD", "name": "US Dollar" }] }

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Lead created successfully
`400`	Bad request (missing/invalid fields)
`401`	Unauthorized (invalid or missing API key)
`403`	Forbidden (IP not whitelisted)
`409`	Conflict (duplicate email)
`500`	Internal server error

Support

For integration support, IP whitelisting requests, or API key issues, please contact your account manager.