Seller API v1

Seller API Reference

Submit leads directly to LeadMatrix via HTTP. Your leads are authenticated, validated, and processed automatically. You get postbacks when conversions are confirmed.

Base URLhttps://leadmatrix.io
REST JSON APIAlways HTTPS

Authentication

Every request must include your API key. Keys start with afx_ and are issued by your LeadMatrix account manager. Keep your key secret — treat it like a password.

Option 1 — Header (recommended)

X-API-Key: afx_YOUR_KEY

Option 2 — Bearer token

Authorization: Bearer afx_YOUR_KEY

Rate limit: 200 requests per IP per minute. Exceeding this returns HTTP 429 — implement exponential back-off.

Submit a lead

POST/api/v1/leads

Sends a lead to LeadMatrix. The lead is validated, stored, and processed automatically. The response includes the lead ID you should store for status checks and postback matching.

cURL example
curl -X POST https://leadmatrix.io/api/v1/leads \
  -H "X-API-Key: afx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "phone": "+4917612345678",
    "first_name": "John",
    "last_name": "Doe",
    "country": "DE",
    "click_id": "your_click_id_here"
  }'

Success response — 200

{
  "lead_id": "a3f1c2d4-...",
  "status": "in_progress",
  "redirect_url": null
}

Validation error — 400

{
  "error": "email is required"
}

Tip: Store the returned lead_id alongside your click_id. You'll receive this ID in postbacks so you can match FTDs back to your traffic.

Check lead status

GET/api/v1/leads/:id

Returns the current status of a lead. Use this to confirm relay or to poll for FTD status if you are not using postbacks.

cURL example
curl https://leadmatrix.io/api/v1/leads/LEAD_ID \
  -H "X-API-Key: afx_YOUR_API_KEY"

Note: You can only fetch leads that belong to your API key's deal. Attempting to fetch another deal's lead returns HTTP 404.

Postbacks (conversion tracking)

When a conversion is confirmed (FTD, deposit, etc.), LeadMatrix fires a postback to your configured URL. You must provide your postback URL to your LeadMatrix account manager so it can be set up in the system.

Postback URL template

https://your-tracker.com/postback?click_id=[[click_id]]&payout=[[payout]]&event=[[event_type]]&lead_id=[[lead_id]]

Supported placeholder syntaxes

[[param]]Recommended
{param}Alternative
%param%Alternative
[param]Alternative

Available postback parameters

ParameterDescription
click_idYour original click ID — use this to match to your traffic
lead_idLeadMatrix lead UUID
event_typeftd | deposit | conversion | chargeback
payoutAgreed payout amount for this event
geoLead country code (DE, GB, etc.)
sub1Your original sub1 parameter
sub2Your original sub2 parameter
sub3Your original sub3 parameter

Field reference

All fields sent in the JSON body of POST /api/v1/leads.

FieldTypeRequiredNotes
emailstringrequiredLead email address
phonestringrequiredPhone number — any format accepted (e.g. +4917612345678 or 00491761...)
first_namestringoptionalLead first name
last_namestringoptionalLead last name
countrystringrequired2-letter country code (ISO 3166-1 alpha-2). Example: DE, GB, US
ipstringoptionalLead IP address (IPv4 or IPv6)
click_idstringoptionalYour tracking / click ID — sent back in postbacks to match conversions
sub1stringoptionalCustom sub-parameter 1 (campaign, source, etc.)
sub2stringoptionalCustom sub-parameter 2
sub3stringoptionalCustom sub-parameter 3

Lead statuses

StatusMeaning
in_progressLead received and being processed — check again shortly
relayedLead delivered and accepted
ftdFirst-time deposit confirmed
rejectedLead rejected (duplicate, invalid fields, etc.)

Error codes

HTTP StatusMeaningAction
400Validation error — missing or invalid fieldFix the request body and retry
401Missing or invalid API keyCheck your X-API-Key header
403API key revoked or deal inactiveContact your account manager
404Lead not found (status check)Verify the lead ID
429Rate limit exceeded (200 req/min)Back off and retry after 1 minute
500Server errorRetry with back-off; contact support if persistent

Code examples

JavaScript / Node.js

fetch example
const res = await fetch("https://leadmatrix.io/api/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "afx_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "john.doe@example.com",
    phone: "+4917612345678",
    first_name: "John",
    last_name: "Doe",
    country: "DE",
    click_id: "your_click_id",
  }),
});

const lead = await res.json();
console.log(lead.lead_id, lead.status);

PHP

cURL (PHP)
$ch = curl_init("https://leadmatrix.io/api/v1/leads");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    "X-API-Key: afx_YOUR_API_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS     => json_encode([
    "email"      => "john.doe@example.com",
    "phone"      => "+4917612345678",
    "first_name" => "John",
    "last_name"  => "Doe",
    "country"    => "DE",
    "click_id"   => "your_click_id",
  ]),
]);

$response = json_decode(curl_exec($ch), true);
echo $response["lead_id"];

Need help with your integration?

Your account manager is available on Telegram.

Contact support