API Integration
Documentation
Push leads into FunnelBox in real time and pull back your clients with their status and first-deposit date. Plain JSON over HTTPS, one bearer token, two endpoints.
https://api.funnelbox.netAuthorization: Bearer <token>Authentication
All requests must include a Bearer Token in the Authorization header. Your token is issued by your account manager together with this documentation.
Use it only from your servers, never in browser or mobile app code. If it leaks, ask us to rotate it. The old token stops working immediately.
Try the examples with your token
Authorization: Bearer YOUR_API_TOKEN
{
"success": false,
"error": "invalid_token",
"detail": "Invalid API token."
}
IP whitelist
Requests are accepted only from whitelisted IP addresses. Contact support to add your server IP addresses to the whitelist.
Send us every public IPv4/IPv6 address your integration calls from. Ranges in CIDR notation (for example 203.0.113.0/24) are supported. A request from any other address is rejected with 403 ip_not_whitelisted, and the response includes the IP we saw, so you can forward it to us.
{
"success": false,
"error": "ip_not_whitelisted",
"detail": "Requests from IP 203.0.113.10 are not allowed. Contact support to add your server IP addresses to the whitelist.",
"ip": "203.0.113.10"
}
Retrieve Your Clients
Get a paginated, filterable list of clients associated with your affiliate account.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
skip | integer | 0 | Records to skip (pagination offset) |
limit | integer | 100 | Max records returned (max 1000) |
search | string | — | Search by ID, name, email, phone, source, 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) |
sort_by | string | created_at | Sort field — created_at, ftd_date, first_name, last_name, email, phone, or id |
sort_order | string | desc | Sort direction: asc or desc |
Response
total is the number of clients matching your filters (ignoring skip/limit). data holds the current page of client objects. To read everything, keep requesting with skip = skip + limit until skip ≥ total.
Poll with ftd_date_start to get every client that made a first deposit since your last sync, e.g. ?ftd_date_start=2026-11-01&sort_by=ftd_date.
curl -X GET "https://api.funnelbox.net/v1/clients?skip=0&limit=10&sort_by=created_at&sort_order=desc" \
-H 'Authorization: Bearer YOUR_API_TOKEN'import requests
response = requests.get(
"https://api.funnelbox.net/v1/clients",
headers={"Authorization": "Bearer YOUR_API_TOKEN"},
params={"skip": 0, "limit": 10, "sort_by": "created_at", "sort_order": "desc"},
timeout=30,
)
response.raise_for_status()
page = response.json()
for client in page["data"]:
print(client["id"], client["email"], client["status"], client["ftd_date"])<?php
$ch = curl_init("https://api.funnelbox.net/v1/clients?skip=0&limit=10&sort_by=created_at&sort_order=desc");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_TOKEN"],
CURLOPT_TIMEOUT => 30,
]);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($page["data"] as $client) {
echo $client["id"] . " " . $client["status"] . PHP_EOL;
}const response = await fetch(
"https://api.funnelbox.net/v1/clients?skip=0&limit=10&sort_by=created_at&sort_order=desc",
{ headers: { Authorization: "Bearer YOUR_API_TOKEN" } }
);
const { total, data } = await response.json();
console.log(`Fetched ${data.length} of ${total} clients`);
{
"total": 100,
"data": [
{
"id": 1,
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+1234567890",
"created_at": "2023-01-15T10:00:00Z",
"ftd_date": "2023-02-01T12:00:00Z",
"register_ip": "192.168.1.1",
"status": "Active",
"source": "testSource",
"country": "United States"
}
],
"skip": 0,
"limit": 10
}
Create a New Lead
Register a new client lead. Provide a valid country_iso. The brand is assigned automatically.
Required fields
| Field | Type | Description |
|---|---|---|
first_namerequired | string | Client first name |
last_namerequired | string | Client last name |
emailrequired | string | Client email address (must be unique) |
phonerequired | string | Client phone number |
country_isorequired | string | ISO 3166-1 alpha-2 country code |
Optional fields
| Field | Type | Description |
|---|---|---|
password | string | Optional. Omit or leave empty to auto-generate. |
source | string | Lead source identifier |
source_id | integer | Numeric source ID |
marketing_details | string | Additional marketing metadata |
register_ip | string | Client IP at point of registration |
balance_currency | string | Allowed values: ["USD", "EUR", "GBP", "JPY", "AUD"] |
Response
client_id is the client's permanent ID; it appears as id in GET /v1/clients. Redirect your user to account_url straight after registration to sign them into their trading account.
Send the body as JSON with Content-Type: application/json. Emails are unique across the platform; re-sending an existing email returns 409 duplicate_email. Phone numbers are stored in international format, so include the country prefix.
curl -X POST https://api.funnelbox.net/v1/leads \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"password": "",
"email": "[email protected]",
"phone": "+1234567890",
"country_iso": "US",
"source": "AffiliateWebsite",
"source_id": 123,
"marketing_details": "CampaignX-PromoY",
"register_ip": "192.168.1.100",
"balance_currency": "USD"
}'import requests
lead = {
"first_name": "John",
"last_name": "Doe",
"password": "",
"email": "[email protected]",
"phone": "+1234567890",
"country_iso": "US",
"source": "AffiliateWebsite",
"source_id": 123,
"marketing_details": "CampaignX-PromoY",
"register_ip": "192.168.1.100",
"balance_currency": "USD",
}
response = requests.post(
"https://api.funnelbox.net/v1/leads",
headers={"Authorization": "Bearer YOUR_API_TOKEN"},
json=lead,
timeout=30,
)
result = response.json()
if result.get("success"):
print("Client", result["client_id"], "->", result["account_url"])
else:
print("Rejected:", response.status_code, result.get("detail"))<?php
$lead = [
"first_name" => "John",
"last_name" => "Doe",
"password" => "",
"email" => "[email protected]",
"phone" => "+1234567890",
"country_iso" => "US",
"source" => "AffiliateWebsite",
"source_id" => 123,
"marketing_details" => "CampaignX-PromoY",
"register_ip" => "192.168.1.100",
"balance_currency" => "USD",
];
$ch = curl_init("https://api.funnelbox.net/v1/leads");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($lead),
CURLOPT_TIMEOUT => 30,
]);
$result = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if (!empty($result["success"])) {
header("Location: " . $result["account_url"]); // send the client into their account
} else {
error_log("Lead rejected ($status): " . $result["detail"]);
}const response = await fetch("https://api.funnelbox.net/v1/leads", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
first_name: "John",
last_name: "Doe",
password: "",
email: "[email protected]",
phone: "+1234567890",
country_iso: "US",
source: "AffiliateWebsite",
source_id: 123,
marketing_details: "CampaignX-PromoY",
register_ip: "192.168.1.100",
balance_currency: "USD",
}),
});
const result = await response.json();
if (result.success) {
console.log(`Client ${result.client_id}: ${result.account_url}`);
} else {
console.error(response.status, result.detail);
}
{
"client_id": 12345,
"success": true,
"account_url": "https://brand-domain.com/landing?token=abc"
}
{
"success": false,
"error": "duplicate_email",
"detail": "A client with this email already exists."
}
Errors
Successful calls return 200. Errors use standard HTTP status codes and always return the same JSON envelope: success: false, a machine-readable error code and a human-readable detail. Validation errors also list every invalid field in errors[].
| Status | Error code | Meaning |
|---|---|---|
400 | invalid_json | The request body is not valid JSON. |
401 | missing_token | The Authorization header is missing or is not a Bearer token. |
401 | invalid_token | The token is not recognised. Check for copy and paste errors. |
403 | ip_not_whitelisted | The request came from an IP address that is not on your whitelist. |
403 | account_paused | Your affiliate account is paused. |
404 | not_found | The endpoint does not exist. Check the URL and the /v1 prefix. |
405 | method_not_allowed | The HTTP method is not supported by this endpoint. |
409 | duplicate_email | A client with this email address already exists. |
413 | payload_too_large | The request body exceeds 64 KB. |
422 | validation_error | One or more fields or query parameters are invalid. See errors[]. |
500 | internal_error | Unexpected server error. Safe to retry. |
503 | no_brand_available | No brand is currently accepting leads. |
Every response carries an X-Request-Id header. Include it when you contact support and we can find the exact request in seconds.
{
"success": false,
"error": "validation_error",
"detail": "Request validation failed.",
"errors": [
{
"field": "country_iso",
"message": "Invalid country_iso. Use an ISO 3166-1 alpha-2 code, e.g. US, GB, DE."
}
]
}
Client object
Returned in the data array of GET /v1/clients.
| Field | Type | Description |
|---|---|---|
id | integer | Unique client ID — the client_id returned when the lead was created |
first_name | string | Client first name |
last_name | string | Client last name |
email | string | Client email address |
phone | string | Client phone number |
created_at | datetime | Registration time (ISO 8601, UTC) |
ftd_date | datetime | null | First deposit time (ISO 8601, UTC); null until the client deposits |
register_ip | string | null | Client IP at point of registration |
status | string | Current client status |
source | string | null | Lead source identifier you supplied |
country | string | Country name |
Client statuses
The status field reflects where the client is in our sales process. New leads start as New; clients who made a first deposit are marked Depositor and receive an ftd_date.
Country codes
country_iso takes an ISO 3166-1 alpha-2 code. Codes are case-insensitive.
AFAfghanistanALAlbaniaDZAlgeriaASAmerican SamoaADAndorraAOAngolaAIAnguillaAQAntarcticaAGAntigua and BarbudaARArgentinaAMArmeniaAWArubaAUAustraliaATAustriaAZAzerbaijanBSBahamasBHBahrainBDBangladeshBBBarbadosBYBelarusBEBelgiumBZBelizeBJBeninBMBermudaBTBhutanBOBoliviaBQBonaire, Sint Eustatius and SabaBABosnia and HerzegovinaBWBotswanaBVBouvet IslandBRBrazilIOBritish Indian Ocean TerritoryBNBruneiBGBulgariaBFBurkina FasoBIBurundiCVCabo VerdeKHCambodiaCMCameroonCACanadaKYCayman IslandsCFCentral African RepublicTDChadCLChileCNChinaCXChristmas IslandCCCocos (Keeling) IslandsCOColombiaKMComorosCGCongoCKCook IslandsCRCosta RicaHRCroatiaCUCubaCWCuraçaoCYCyprusCZCzechiaCICôte d'IvoireCDDR CongoDKDenmarkDJDjiboutiDMDominicaDODominican RepublicECEcuadorEGEgyptSVEl SalvadorGQEquatorial GuineaEREritreaEEEstoniaSZEswatiniETEthiopiaFKFalkland Islands (Malvinas)FOFaroe IslandsFJFijiFIFinlandFRFranceGFFrench GuianaPFFrench PolynesiaTFFrench Southern TerritoriesGAGabonGMGambiaGEGeorgiaDEGermanyGHGhanaGIGibraltarGRGreeceGLGreenlandGDGrenadaGPGuadeloupeGUGuamGTGuatemalaGGGuernseyGNGuineaGWGuinea-BissauGYGuyanaHTHaitiHMHeard Island and McDonald IslandsHNHondurasHKHong KongHUHungaryISIcelandINIndiaIDIndonesiaIRIranIQIraqIEIrelandIMIsle of ManILIsraelITItalyJMJamaicaJPJapanJEJerseyJOJordanKZKazakhstanKEKenyaKIKiribatiKWKuwaitKGKyrgyzstanLALaosLVLatviaLBLebanonLSLesothoLRLiberiaLYLibyaLILiechtensteinLTLithuaniaLULuxembourgMOMacaoMGMadagascarMWMalawiMYMalaysiaMVMaldivesMLMaliMTMaltaMHMarshall IslandsMQMartiniqueMRMauritaniaMUMauritiusYTMayotteMXMexicoFMMicronesiaMDMoldovaMCMonacoMNMongoliaMEMontenegroMSMontserratMAMoroccoMZMozambiqueMMMyanmarNANamibiaNRNauruNPNepalNLNetherlandsNCNew CaledoniaNZNew ZealandNINicaraguaNENigerNGNigeriaNUNiueNFNorfolk IslandKPNorth KoreaMKNorth MacedoniaMPNorthern Mariana IslandsNONorwayOMOmanPKPakistanPWPalauPSPalestinePAPanamaPGPapua New GuineaPYParaguayPEPeruPHPhilippinesPNPitcairnPLPolandPTPortugalPRPuerto RicoQAQatarRORomaniaRURussiaRWRwandaRERéunionBLSaint BarthélemySHSaint Helena, Ascension and Tristan da CunhaKNSaint Kitts and NevisLCSaint LuciaMFSaint Martin (French part)PMSaint Pierre and MiquelonVCSaint Vincent and the GrenadinesWSSamoaSMSan MarinoSTSao Tome and PrincipeSASaudi ArabiaSNSenegalRSSerbiaSCSeychellesSLSierra LeoneSGSingaporeSXSint Maarten (Dutch part)SKSlovakiaSISloveniaSBSolomon IslandsSOSomaliaZASouth AfricaGSSouth Georgia and the South Sandwich IslandsKRSouth KoreaSSSouth SudanESSpainLKSri LankaSDSudanSRSurinameSJSvalbard and Jan MayenSESwedenCHSwitzerlandSYSyriaTWTaiwanTJTajikistanTZTanzaniaTHThailandTLTimor-LesteTGTogoTKTokelauTOTongaTTTrinidad and TobagoTNTunisiaTMTurkmenistanTCTurks and Caicos IslandsTVTuvaluTRTürkiyeUGUgandaUAUkraineAEUnited Arab EmiratesGBUnited KingdomUSUnited StatesUMUnited States Minor Outlying IslandsUYUruguayUZUzbekistanVUVanuatuVAVatican CityVEVenezuelaVNVietnamVGVirgin Islands, BritishVIVirgin Islands, U.S.WFWallis and FutunaEHWestern SaharaYEYemenZMZambiaZWZimbabweAXÅland IslandsGo-live checklist
- Your server IP addresses are whitelisted. Test with a single lead and check for
200. - The token is stored server-side (environment variable or secret manager), never in front-end code.
- You send
country_isoas a 2-letter code and phone numbers with the international prefix. - You store the returned
client_idand redirect the user toaccount_url. - You handle
409(duplicate) and422(validation) without retrying. Retry5xxwith backoff. - You sync statuses and FTDs with
GET /v1/clientsusingftd_date_start/created_at_start, at most once a minute.