LeadTerminal
v1

Vendor Posting API

How to send leads into Lead Terminal: one request per lead, in real time, by direct post or ping/post. Every response tells you right away whether the lead was accepted and why if it wasn't.

01Before you start

When your account is approved you receive two things:

  • Your API key. It identifies you on every request. Keep it private; we can rotate it any time.
  • Your campaign slugs, such as final-expense. Each campaign you are enabled for has its own slug and its own printable spec listing the exact fields, which are required, and the formats we accept.
This page covers the API that every campaign shares. Your campaign spec is the final word on which fields a campaign requires. Haven't signed up yet? Apply to sell leads.

02Endpoint

Method
POST (recommended) or GET
URL
https://leadterminal.io/api/v1/leads/{campaign}
Body
JSON (application/json), form (application/x-www-form-urlencoded) or XML
Auth
X-API-Key header, or an api_key field in the body or query string

You can also post to https://leadterminal.io/api/v1/leads and send the slug in a campaign field.

03Minimum request

The smallest lead most campaigns accept. Your campaign spec may require more.

JSON
{
  "first_name": "Mary",
  "last_name": "Jones",
  "phone": "(619) 555-0101",
  "state": "CA",
  "zip": "92108"
}

04Full example

A typical final expense lead with consent and tracking. Names and numbers are placeholders.

JSON
{
  "first_name": "Mary",
  "last_name": "Jones",
  "phone": "6195550101",
  "email": "mary.jones@example.com",
  "address": "1200 Camino Real",
  "city": "San Diego",
  "state": "CA",
  "zip": "92108",
  "dob": "1955-04-12",
  "gender": "female",
  "tobacco": false,
  "coverage_amount": 15000,
  "ip_address": "73.12.44.210",
  "tcpa_consent": true,
  "trustedform_cert_url": "https://cert.trustedform.com/2f8c...",
  "jornaya_leadid": "8A1C2E44-...-91D0",
  "landing_page_url": "https://yoursite.com/final-expense",
  "sub_id": "fb-221",
  "utm_source": "facebook",
  "utm_campaign": "fe-nov"
}

05cURL and GET

POST
curl -X POST https://leadterminal.io/api/v1/leads/final-expense \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Mary","last_name":"Jones","phone":"6195550101","state":"CA","zip":"92108"}'

If your system can only fire a URL, send the same fields as a query string with GET:

GET
https://leadterminal.io/api/v1/leads/final-expense?api_key=YOUR_API_KEY&first_name=Mary&last_name=Jones&phone=6195550101&state=CA&zip=92108

06Responses

Every response is JSON. Store lead_id with your own record; it's the reference for returns, disputes and support.

Accepted

HTTP 200
{
  "status": "accepted",
  "lead_id": 48213,
  "lead_uuid": "7c1e0b7a-3a51-4f2e-9a0e-6b1d2f0c9e41",
  "sold": true
}

Rejected

HTTP 200
{
  "status": "rejected",
  "lead_id": 48214,
  "lead_uuid": "0f9d4c22-8b3e-4c0a-a7e2-1f6b9d3e5a70",
  "errors": ["phone: invalid phone", "dob: invalid date (use YYYY-MM-DD or MM/DD/YYYY)"],
  "message": "validation failed"
}
statusMeaningWhat to do
acceptedThe lead passed every check. sold shows whether it sold on this request.Nothing. You're paid per your campaign terms.
rejectedA field failed validation (see errors), the campaign is paused, you aren't enabled for it, or your daily cap is reached (see message).Fix the fields listed and resend. Don't resend unchanged.
duplicateWe already have this lead within the campaign's duplicate window. message names the matching field and lead.Don't resend.
suppressedThe phone or email is on a do-not-contact list, including DNC and litigator scrubs.Remove the consumer from your list.
errorThe request itself is wrong. Comes with an HTTP 4xx code and a message.See the table below.
HTTPmessageFix
400could not parse body as ...Send valid JSON, form or XML that matches your Content-Type.
400missing campaign ...Use /leads/{campaign} or send a campaign field.
401missing api_key or invalid api_keySend your key in X-API-Key or api_key.
404unknown campaign "..."Check the slug in your campaign spec.

07Field reference

The common fields below are named the same in every campaign. Field names are lowercase with underscores. Fields you send that aren't in a campaign's spec are stored and passed along where buyers ask for them.

FieldTypeFormat and notes
phonephoneRequiredAny readable US format: 6195550101, (619) 555-0101, +16195550101. Stored as 10 digits.
first_namestringUsually required
last_namestringUsually required
statestateUsually requiredTwo letter code (CA) or full name (California).
zipzipUsually required5 digits, or ZIP+4.
emailemailOptional
addressstringOptionalStreet line.
citystringOptional
dobdateOptionalYYYY-MM-DD or MM/DD/YYYY. Stored as YYYY-MM-DD.
genderenumOptionalmale or female.
tobaccobooleanOptionaltrue/false; yes/no and 1/0 are also accepted.
coverage_amountnumberOptionalWhole dollars, no symbols.
ip_addressIPOften requiredThe consumer's IPv4 or IPv6 address.
tcpa_consentbooleanOften requiredWhether the consumer gave express written consent.
trustedform_cert_urlURLOften requiredFull certificate URL.
jornaya_leadidstringOptionalJornaya LeadiD token.
landing_page_urlURLOptionalPage where consent was captured.
sub_idstringOptionalYour traffic source or sub-affiliate ID. Reported back to you on every lead.
api_keystringIf no headerOnly when you don't send X-API-Key.
teststringOptionalSee Test mode.

Vertical fields (Medicare plan type, vehicle year, home value, debt amount and so on) are listed in each campaign's spec.

08Tracking and consent

  • Send sub_id on every lead so your earnings and statements break down by source.
  • UTM fields (utm_source, utm_medium, utm_campaign, utm_content, utm_term) and your own IDs are stored as sent. Keep key names consistent across posts.
  • Consent proof (tcpa_consent, trustedform_cert_url, jornaya_leadid, ip_address, landing_page_url) is passed to buyers that require it. Leads without it can be rejected on campaigns that require it.
  • Every phone number is checked against our suppression lists, and on campaigns that require it, against federal, state and litigator DNC lists. Numbers that hit come back suppressed.

09Ping/post

Use ping/post when you want a price before you send contact details.

1. Ping

Send the non-contact fields (state, zip, age or dob, vertical answers, no name, phone or email) to:

POST
https://leadterminal.io/api/v1/ping/{campaign}
Ping response
{
  "status": "accepted",
  "accepted": true,
  "ping_id": "PING_ID",
  "bid": 46,
  "expires_in": 60
}

bid is what we pay for the full lead, in US dollars. expires_in is how many seconds the offer stands. A ping with no buyer interest returns "status": "rejected" with a reason.

2. Post

Post the full lead to https://leadterminal.io/api/v1/leads/{campaign} with the ping_id before the offer expires. The response adds price, the amount you're paid.

Post response
{
  "status": "accepted",
  "lead_id": 48213,
  "lead_uuid": "7c1e0b7a-3a51-4f2e-9a0e-6b1d2f0c9e41",
  "sold": true,
  "price": "46.00"
}

A ping_id works once. Posting after it expires or posting it twice returns rejected with ping expired or ping already used.

10Test mode

Add a test field to any post or ping while you integrate. Test leads are never sold and never paid.

ValueWhat happens
test=trueRuns every live check (fields, duplicates, suppression, DNC) and returns a field-by-field report: what you sent, how we stored it, and any error.
test=deliverSame as above, and also sends the lead to buyer test endpoints so you can confirm the full path end to end.

Remove test to go live.

11Web form redirects

If your form posts straight from the consumer's browser, add redirect=1 and we send the browser to your thank-you or error page instead of returning JSON.

  • success_url: where accepted leads go. fail_url: where everything else goes.
  • We add status and lead_id to the URL, plus message on failures.
  • If you don't send the URLs, the campaign's default pages are used.

12Rules

  • One lead per request, sent in real time, as the consumer submits.
  • Send booleans as true/false in JSON. Form and GET posts can send true, yes or 1.
  • Don't resend a lead that came back rejected, duplicate or suppressed without fixing the cause.
  • Only send leads from consumers who gave consent for the campaign's vertical, with proof you can produce on request.
  • Keep your API key on your server. Never put it in a page a consumer can view; use redirect=1 through your own server instead.

Need help?

Sign in and contact your account manager with a sample payload, and we'll confirm your integration end to end.

Apply to sell leads