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.
https://leadmatrix.ioAuthentication
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_KEYOption 2 — Bearer token
Authorization: Bearer afx_YOUR_KEYRate limit: 200 requests per IP per minute. Exceeding this returns HTTP 429 — implement exponential back-off.
Submit a lead
/api/v1/leadsSends 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 -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
/api/v1/leads/:idReturns the current status of a lead. Use this to confirm relay or to poll for FTD status if you are not using postbacks.
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]AlternativeAvailable postback parameters
| Parameter | Description |
|---|---|
click_id | Your original click ID — use this to match to your traffic |
lead_id | LeadMatrix lead UUID |
event_type | ftd | deposit | conversion | chargeback |
payout | Agreed payout amount for this event |
geo | Lead country code (DE, GB, etc.) |
sub1 | Your original sub1 parameter |
sub2 | Your original sub2 parameter |
sub3 | Your original sub3 parameter |
Field reference
All fields sent in the JSON body of POST /api/v1/leads.
| Field | Type | Required | Notes |
|---|---|---|---|
email | string | required | Lead email address |
phone | string | required | Phone number — any format accepted (e.g. +4917612345678 or 00491761...) |
first_name | string | optional | Lead first name |
last_name | string | optional | Lead last name |
country | string | required | 2-letter country code (ISO 3166-1 alpha-2). Example: DE, GB, US |
ip | string | optional | Lead IP address (IPv4 or IPv6) |
click_id | string | optional | Your tracking / click ID — sent back in postbacks to match conversions |
sub1 | string | optional | Custom sub-parameter 1 (campaign, source, etc.) |
sub2 | string | optional | Custom sub-parameter 2 |
sub3 | string | optional | Custom sub-parameter 3 |
Lead statuses
| Status | Meaning |
|---|---|
| in_progress | Lead received and being processed — check again shortly |
| relayed | Lead delivered and accepted |
| ftd | First-time deposit confirmed |
| rejected | Lead rejected (duplicate, invalid fields, etc.) |
Error codes
| HTTP Status | Meaning | Action |
|---|---|---|
400 | Validation error — missing or invalid field | Fix the request body and retry |
401 | Missing or invalid API key | Check your X-API-Key header |
403 | API key revoked or deal inactive | Contact your account manager |
404 | Lead not found (status check) | Verify the lead ID |
429 | Rate limit exceeded (200 req/min) | Back off and retry after 1 minute |
500 | Server error | Retry with back-off; contact support if persistent |
Code examples
JavaScript / Node.js
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
$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.