Funnelbox Affiliate API v1 https://api.funnelbox.net Postman collection
// AFFILIATE API · v1

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.

Base URLhttps://api.funnelbox.net
AuthenticationAuthorization: Bearer <token>
FormatJSON · UTF-8 · ISO 8601 dates (UTC)

Authentication

All requests must include a Bearer Token in the Authorization header. Your token is issued by your account manager together with this documentation.

Keep your token secret

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

Request header
Authorization: Bearer YOUR_API_TOKEN
401 · invalid_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.

403 · ip_not_whitelisted
{
  "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

GEThttps://api.funnelbox.net/v1/clients BEARER TOKEN

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

Query parameters

ParameterTypeDefaultDescription
skipinteger0Records to skip (pagination offset)
limitinteger100Max records returned (max 1000)
searchstring—Search by ID, name, email, phone, source, or status
created_at_startdate—Registered on or after this date (YYYY-MM-DD)
created_at_enddate—Registered on or before this date (YYYY-MM-DD)
ftd_date_startdate—First deposit on or after (YYYY-MM-DD)
ftd_date_enddate—First deposit on or before (YYYY-MM-DD)
sort_bystringcreated_atSort field — created_at, ftd_date, first_name, last_name, email, phone, or id
sort_orderstringdescSort 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.

Tracking FTDs

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'
200 · OK
{
  "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

POSThttps://api.funnelbox.net/v1/leads BEARER TOKEN

Register a new client lead. Provide a valid country_iso. The brand is assigned automatically.

Required fields

FieldTypeDescription
first_namerequiredstringClient first name
last_namerequiredstringClient last name
emailrequiredstringClient email address (must be unique)
phonerequiredstringClient phone number
country_isorequiredstringISO 3166-1 alpha-2 country code

Optional fields

FieldTypeDescription
passwordstringOptional. Omit or leave empty to auto-generate.
sourcestringLead source identifier
source_idintegerNumeric source ID
marketing_detailsstringAdditional marketing metadata
register_ipstringClient IP at point of registration
balance_currencystringAllowed 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.

Good to know

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"
  }'
200 · OK
{
  "client_id": 12345,
  "success": true,
  "account_url": "https://brand-domain.com/landing?token=abc"
}
409 · duplicate_email
{
  "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[].

StatusError codeMeaning
400invalid_jsonThe request body is not valid JSON.
401missing_tokenThe Authorization header is missing or is not a Bearer token.
401invalid_tokenThe token is not recognised. Check for copy and paste errors.
403ip_not_whitelistedThe request came from an IP address that is not on your whitelist.
403account_pausedYour affiliate account is paused.
404not_foundThe endpoint does not exist. Check the URL and the /v1 prefix.
405method_not_allowedThe HTTP method is not supported by this endpoint.
409duplicate_emailA client with this email address already exists.
413payload_too_largeThe request body exceeds 64 KB.
422validation_errorOne or more fields or query parameters are invalid. See errors[].
500internal_errorUnexpected server error. Safe to retry.
503no_brand_availableNo 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.

422 · validation_error
{
  "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.

FieldTypeDescription
idintegerUnique client ID — the client_id returned when the lead was created
first_namestringClient first name
last_namestringClient last name
emailstringClient email address
phonestringClient phone number
created_atdatetimeRegistration time (ISO 8601, UTC)
ftd_datedatetime | nullFirst deposit time (ISO 8601, UTC); null until the client deposits
register_ipstring | nullClient IP at point of registration
statusstringCurrent client status
sourcestring | nullLead source identifier you supplied
countrystringCountry 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.

NewActiveNo AnswerCall BackInterestedNot InterestedInvalidDepositor

Country codes

country_iso takes an ISO 3166-1 alpha-2 code. Codes are case-insensitive.

🇦🇫AFAfghanistan
🇦🇱ALAlbania
🇩🇿DZAlgeria
🇦🇸ASAmerican Samoa
🇦🇩ADAndorra
🇦🇴AOAngola
🇦🇮AIAnguilla
🇦🇶AQAntarctica
🇦🇬AGAntigua and Barbuda
🇦🇷ARArgentina
🇦🇲AMArmenia
🇦🇼AWAruba
🇦🇺AUAustralia
🇦🇹ATAustria
🇦🇿AZAzerbaijan
🇧🇸BSBahamas
🇧🇭BHBahrain
🇧🇩BDBangladesh
🇧🇧BBBarbados
🇧🇾BYBelarus
🇧🇪BEBelgium
🇧🇿BZBelize
🇧🇯BJBenin
🇧🇲BMBermuda
🇧🇹BTBhutan
🇧🇴BOBolivia
🇧🇶BQBonaire, Sint Eustatius and Saba
🇧🇦BABosnia and Herzegovina
🇧🇼BWBotswana
🇧🇻BVBouvet Island
🇧🇷BRBrazil
🇮🇴IOBritish Indian Ocean Territory
🇧🇳BNBrunei
🇧🇬BGBulgaria
🇧🇫BFBurkina Faso
🇧🇮BIBurundi
🇨🇻CVCabo Verde
🇰🇭KHCambodia
🇨🇲CMCameroon
🇨🇦CACanada
🇰🇾KYCayman Islands
🇨🇫CFCentral African Republic
🇹🇩TDChad
🇨🇱CLChile
🇨🇳CNChina
🇨🇽CXChristmas Island
🇨🇨CCCocos (Keeling) Islands
🇨🇴COColombia
🇰🇲KMComoros
🇨🇬CGCongo
🇨🇰CKCook Islands
🇨🇷CRCosta Rica
🇭🇷HRCroatia
🇨🇺CUCuba
🇨🇼CWCuraçao
🇨🇾CYCyprus
🇨🇿CZCzechia
🇨🇮CICôte d'Ivoire
🇨🇩CDDR Congo
🇩🇰DKDenmark
🇩🇯DJDjibouti
🇩🇲DMDominica
🇩🇴DODominican Republic
🇪🇨ECEcuador
🇪🇬EGEgypt
🇸🇻SVEl Salvador
🇬🇶GQEquatorial Guinea
🇪🇷EREritrea
🇪🇪EEEstonia
🇸🇿SZEswatini
🇪🇹ETEthiopia
🇫🇰FKFalkland Islands (Malvinas)
🇫🇴FOFaroe Islands
🇫🇯FJFiji
🇫🇮FIFinland
🇫🇷FRFrance
🇬🇫GFFrench Guiana
🇵🇫PFFrench Polynesia
🇹🇫TFFrench Southern Territories
🇬🇦GAGabon
🇬🇲GMGambia
🇬🇪GEGeorgia
🇩🇪DEGermany
🇬🇭GHGhana
🇬🇮GIGibraltar
🇬🇷GRGreece
🇬🇱GLGreenland
🇬🇩GDGrenada
🇬🇵GPGuadeloupe
🇬🇺GUGuam
🇬🇹GTGuatemala
🇬🇬GGGuernsey
🇬🇳GNGuinea
🇬🇼GWGuinea-Bissau
🇬🇾GYGuyana
🇭🇹HTHaiti
🇭🇲HMHeard Island and McDonald Islands
🇭🇳HNHonduras
🇭🇰HKHong Kong
🇭🇺HUHungary
🇮🇸ISIceland
🇮🇳INIndia
🇮🇩IDIndonesia
🇮🇷IRIran
🇮🇶IQIraq
🇮🇪IEIreland
🇮🇲IMIsle of Man
🇮🇱ILIsrael
🇮🇹ITItaly
🇯🇲JMJamaica
🇯🇵JPJapan
🇯🇪JEJersey
🇯🇴JOJordan
🇰🇿KZKazakhstan
🇰🇪KEKenya
🇰🇮KIKiribati
🇰🇼KWKuwait
🇰🇬KGKyrgyzstan
🇱🇦LALaos
🇱🇻LVLatvia
🇱🇧LBLebanon
🇱🇸LSLesotho
🇱🇷LRLiberia
🇱🇾LYLibya
🇱🇮LILiechtenstein
🇱🇹LTLithuania
🇱🇺LULuxembourg
🇲🇴MOMacao
🇲🇬MGMadagascar
🇲🇼MWMalawi
🇲🇾MYMalaysia
🇲🇻MVMaldives
🇲🇱MLMali
🇲🇹MTMalta
🇲🇭MHMarshall Islands
🇲🇶MQMartinique
🇲🇷MRMauritania
🇲🇺MUMauritius
🇾🇹YTMayotte
🇲🇽MXMexico
🇫🇲FMMicronesia
🇲🇩MDMoldova
🇲🇨MCMonaco
🇲🇳MNMongolia
🇲🇪MEMontenegro
🇲🇸MSMontserrat
🇲🇦MAMorocco
🇲🇿MZMozambique
🇲🇲MMMyanmar
🇳🇦NANamibia
🇳🇷NRNauru
🇳🇵NPNepal
🇳🇱NLNetherlands
🇳🇨NCNew Caledonia
🇳🇿NZNew Zealand
🇳🇮NINicaragua
🇳🇪NENiger
🇳🇬NGNigeria
🇳🇺NUNiue
🇳🇫NFNorfolk Island
🇰🇵KPNorth Korea
🇲🇰MKNorth Macedonia
🇲🇵MPNorthern Mariana Islands
🇳🇴NONorway
🇴🇲OMOman
🇵🇰PKPakistan
🇵🇼PWPalau
🇵🇸PSPalestine
🇵🇦PAPanama
🇵🇬PGPapua New Guinea
🇵🇾PYParaguay
🇵🇪PEPeru
🇵🇭PHPhilippines
🇵🇳PNPitcairn
🇵🇱PLPoland
🇵🇹PTPortugal
🇵🇷PRPuerto Rico
🇶🇦QAQatar
🇷🇴RORomania
🇷🇺RURussia
🇷🇼RWRwanda
🇷🇪RERéunion
🇧🇱BLSaint Barthélemy
🇸🇭SHSaint Helena, Ascension and Tristan da Cunha
🇰🇳KNSaint Kitts and Nevis
🇱🇨LCSaint Lucia
🇲🇫MFSaint Martin (French part)
🇵🇲PMSaint Pierre and Miquelon
🇻🇨VCSaint Vincent and the Grenadines
🇼🇸WSSamoa
🇸🇲SMSan Marino
🇸🇹STSao Tome and Principe
🇸🇦SASaudi Arabia
🇸🇳SNSenegal
🇷🇸RSSerbia
🇸🇨SCSeychelles
🇸🇱SLSierra Leone
🇸🇬SGSingapore
🇸🇽SXSint Maarten (Dutch part)
🇸🇰SKSlovakia
🇸🇮SISlovenia
🇸🇧SBSolomon Islands
🇸🇴SOSomalia
🇿🇦ZASouth Africa
🇬🇸GSSouth Georgia and the South Sandwich Islands
🇰🇷KRSouth Korea
🇸🇸SSSouth Sudan
🇪🇸ESSpain
🇱🇰LKSri Lanka
🇸🇩SDSudan
🇸🇷SRSuriname
🇸🇯SJSvalbard and Jan Mayen
🇸🇪SESweden
🇨🇭CHSwitzerland
🇸🇾SYSyria
🇹🇼TWTaiwan
🇹🇯TJTajikistan
🇹🇿TZTanzania
🇹🇭THThailand
🇹🇱TLTimor-Leste
🇹🇬TGTogo
🇹🇰TKTokelau
🇹🇴TOTonga
🇹🇹TTTrinidad and Tobago
🇹🇳TNTunisia
🇹🇲TMTurkmenistan
🇹🇨TCTurks and Caicos Islands
🇹🇻TVTuvalu
🇹🇷TRTürkiye
🇺🇬UGUganda
🇺🇦UAUkraine
🇦🇪AEUnited Arab Emirates
🇬🇧GBUnited Kingdom
🇺🇸USUnited States
🇺🇲UMUnited States Minor Outlying Islands
🇺🇾UYUruguay
🇺🇿UZUzbekistan
🇻🇺VUVanuatu
🇻🇦VAVatican City
🇻🇪VEVenezuela
🇻🇳VNVietnam
🇻🇬VGVirgin Islands, British
🇻🇮VIVirgin Islands, U.S.
🇼🇫WFWallis and Futuna
🇪🇭EHWestern Sahara
🇾🇪YEYemen
🇿🇲ZMZambia
🇿🇼ZWZimbabwe
🇦🇽AXÅland Islands

Go-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_iso as a 2-letter code and phone numbers with the international prefix.
  • You store the returned client_id and redirect the user to account_url.
  • You handle 409 (duplicate) and 422 (validation) without retrying. Retry 5xx with backoff.
  • You sync statuses and FTDs with GET /v1/clients using ftd_date_start / created_at_start, at most once a minute.