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.
02Endpoint
POST (recommended) or GEThttps://leadterminal.io/api/v1/leads/{campaign}application/json), form (application/x-www-form-urlencoded) or XMLX-API-Key header, or an api_key field in the body or query stringYou 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.
{
"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.
{
"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
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:
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
{
"status": "accepted",
"lead_id": 48213,
"lead_uuid": "7c1e0b7a-3a51-4f2e-9a0e-6b1d2f0c9e41",
"sold": true
}Rejected
{
"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"
}| status | Meaning | What to do |
|---|---|---|
accepted | The lead passed every check. sold shows whether it sold on this request. | Nothing. You're paid per your campaign terms. |
rejected | A 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. |
duplicate | We already have this lead within the campaign's duplicate window. message names the matching field and lead. | Don't resend. |
suppressed | The phone or email is on a do-not-contact list, including DNC and litigator scrubs. | Remove the consumer from your list. |
error | The request itself is wrong. Comes with an HTTP 4xx code and a message. | See the table below. |
| HTTP | message | Fix |
|---|---|---|
400 | could not parse body as ... | Send valid JSON, form or XML that matches your Content-Type. |
400 | missing campaign ... | Use /leads/{campaign} or send a campaign field. |
401 | missing api_key or invalid api_key | Send your key in X-API-Key or api_key. |
404 | unknown 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.
| Field | Type | Format and notes | |
|---|---|---|---|
phone | phone | Required | Any readable US format: 6195550101, (619) 555-0101, +16195550101. Stored as 10 digits. |
first_name | string | Usually required | |
last_name | string | Usually required | |
state | state | Usually required | Two letter code (CA) or full name (California). |
zip | zip | Usually required | 5 digits, or ZIP+4. |
email | Optional | ||
address | string | Optional | Street line. |
city | string | Optional | |
dob | date | Optional | YYYY-MM-DD or MM/DD/YYYY. Stored as YYYY-MM-DD. |
gender | enum | Optional | male or female. |
tobacco | boolean | Optional | true/false; yes/no and 1/0 are also accepted. |
coverage_amount | number | Optional | Whole dollars, no symbols. |
ip_address | IP | Often required | The consumer's IPv4 or IPv6 address. |
tcpa_consent | boolean | Often required | Whether the consumer gave express written consent. |
trustedform_cert_url | URL | Often required | Full certificate URL. |
jornaya_leadid | string | Optional | Jornaya LeadiD token. |
landing_page_url | URL | Optional | Page where consent was captured. |
sub_id | string | Optional | Your traffic source or sub-affiliate ID. Reported back to you on every lead. |
api_key | string | If no header | Only when you don't send X-API-Key. |
test | string | Optional | See 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_idon 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:
https://leadterminal.io/api/v1/ping/{campaign}{
"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.
{
"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.
| Value | What happens |
|---|---|
test=true | Runs 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=deliver | Same 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
statusandlead_idto the URL, plusmessageon 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/falsein JSON. Form and GET posts can sendtrue,yesor1. - Don't resend a lead that came back
rejected,duplicateorsuppressedwithout 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=1through 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.