Lead API Integration

Lead API — Integration Guide

How to send leads, pull their status, and read deposit results.

Base URL: https://web-app-test-two.onrender.com Auth: API key in X-API-Key header Format: JSON or form-encoded

1. Overview

Two endpoints. You push each lead to us in real time, and you poll for its current status and deposit result on your own schedule. Every request is authenticated with the API key we issue to you, sent in the X-API-Key header. A partner only ever sees its own leads — the key identifies you, so there is no account ID to pass or tamper with.

The two things you asked for: the API key and the base URL are issued per integration. Use the same key for both endpoints below. Send it on every request in the X-API-Key header.

2. Send a lead

POST/api/v1/leads

Post one lead per request. The body may be JSON (application/json) or form-encoded (application/x-www-form-urlencoded). Field names are matched case-insensitively and common aliases are accepted, so most existing integrations work without renaming anything.

Headers

X-API-Key: your_api_key_here
Content-Type: application/json

Body fields

FieldRequiredDescription
emailrequiredLead email address. Must be a valid, non-disposable mailbox.
first_namerequiredFirst name.
phonerequiredPhone in international format. 7–15 digits.
last_nameoptionalLast name.
countryoptionalISO country code (e.g. GB, AU).
languageoptionalLanguage / locale code.
passwordoptionalIf omitted, a secure one is generated and the client sets their own later.
ipoptionalLead's IP at capture.
click_idoptionalYour click / transaction ID. Returned on status and used for de-duplication.
sub_idoptionalSub-affiliate identifier. Use this to identify the specific affiliate behind the lead.
offeroptionalOffer / campaign identifier.
funneloptionalFunnel / landing page name.

Aliases are accepted for every field (e.g. firstName, fname; phone_number, msisdn; clickid, cid; countrycode). Custom parameters such as MPC_1..MPC_12 or adv1..adv10 are stored verbatim and returned on status.

Example request

curl -X POST https://web-app-test-two.onrender.com/api/v1/leads \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+447700900123",
    "country": "GB",
    "language": "en",
    "click_id": "abc123",
    "sub_id": "affiliate_42",
    "offer": "forex_uk",
    "funnel": "landing_v3"
  }'

Success response HTTP 200

{
  "status": true,
  "leadId": "b9f3c2e1-...",       // our internal lead/client ID
  "clientId": "identity-string",  // login identity
  "clickId": "abc123",            // echoed back
  "warnings": []                  // non-blocking notes, e.g. geo mismatch
}

Rejection responses

Every rejection names the exact problem so it can be fixed without a support ticket. The HTTP code tells you whether to retry.

400Body is not valid JSON or form-encoded, or is not an object. 401Invalid, missing, revoked, or IP-blocked API key. Nothing is stored. 403The key is valid but not permitted to post leads, or the integration is disabled. 409Duplicate — we already received this lead from you (matched on email or phone within the dedup window). Response names the match and first-seen date. Do not resend. 413Payload too large (limit 64 KB). 422Invalid lead — a required field is missing or a value is malformed (bad email, disposable mailbox, phone outside 7–15 digits, placeholder text). Fix and resend. 429Cap reached — daily/geo cap exhausted. Retriable: route the lead elsewhere or resend later. 503Intake paused or desk closed. Retriable: your retry scheduler should hold the lead and try again.
Treat 429 and 503 as retriable. They mean the lead was not bad — we simply could not take it at that moment. A rejected lead (422) or duplicate (409) should not be resent as-is.

Rejection body shape:

{
  "status": false,
  "error": "invalid",     // or "duplicate", "cap_exceeded", "desk_closed"
  "message": "phone number length is outside the dialable range"
}

3. Pull lead status & deposits

GET/api/v1/leads/status

Poll this endpoint to read the current status of the leads you sent, including whether they made a first-time deposit and how much. There is no separate deposits endpoint — deposit results are returned inline on each lead, so one poll gives you both status and money.

Headers

X-API-Key: your_api_key_here

Query parameters

ParameterRequiredDescription
fromoptionalOnly return leads created on/after this timestamp (ISO 8601, e.g. 2026-09-01).
tooptionalOnly return leads created on/before this date.
limitoptionalMax rows to return. 1–1000, default 200.

Example request

curl "https://web-app-test-two.onrender.com/api/v1/leads/status?from=2026-09-01&limit=500" \
  -H "X-API-Key: your_api_key_here"

Response HTTP 200

{
  "status": true,
  "count": 2,
  "leads": [
    {
      "leadId": "b9f3c2e1-...",
      "clickId": "abc123",
      "createdAt": "2026-09-01T10:22:41Z",
      "status": "lead",           // lead lifecycle status
      "disposition": "callback",  // agent disposition, if set
      "ftd": true,                // made a first-time deposit?
      "ftdAt": "2026-09-02T14:05:00Z",
      "depositAmount": 250        // total deposited amount
    },
    {
      "leadId": "7c1a44f0-...",
      "clickId": "def456",
      "createdAt": "2026-09-01T11:03:12Z",
      "status": "lead",
      "disposition": "",
      "ftd": false,
      "ftdAt": "",
      "depositAmount": 0
    }
  ]
}

Deposit fields explained

ftdtrue once the lead has made their first-time deposit, otherwise false. ftdAtTimestamp of the first-time deposit. Empty until it happens. depositAmountTotal deposited amount for the lead. 0 until money arrives. statusLead lifecycle status (e.g. lead, and onward as the desk works it). dispositionLatest agent disposition, when one has been set.

Only accepted leads appear here. Poll at whatever interval suits you; the endpoint is rate-limited generously and returns a Retry-After header if you exceed it.

4. Authentication summary