Send Your Own Leads Into InvestorFunnel
If you generate leads outside InvestorFunnel — your own ads, a scraper, another tool — you can push them straight into your pipeline over the API instead of importing a CSV by hand. This is a Gold and Enterprise plan feature.
1. Generate a Key
Go to API Keys in your admin sidebar and click Generate API Key. Name it something you will recognize later (e.g. “Facebook Lead Ads”), and set permissions to Read + Write if you plan to create leads, not just read them. The key is shown once, copy it immediately.
2. Authenticate
Every request carries your key as a bearer token, and request bodies are JSON (a form-encoded body also works):
Authorization: Bearer if_live_<your_key>
Keys are scoped to your account only. Requests are capped at 60 per minute per key by default; each response includes an X-RateLimit-Remaining header so you can watch your headroom.
3. Create a Lead
POST https://investorfunnel.com/api/v1/leads (requires a Read + Write key)
Only email is required. Everything else is optional:
email — required, must be a valid addressfirstname, lastname — up to 100 characters eachphone — up to 20 characters, any formatfunnel_type — seller, buyer, investor, lender, provider, apprentice, or contact (defaults to contact)source — a free-text label, e.g. “Facebook Ads” (defaults to “api”)notes — up to 2,000 characters, saved as the lead’s first notefields — an object of funnel-specific data (see below)external_id, ip_address, user_agent, landing_page_url, referrer_url, trustedform_cert_url, jornaya_leadid, tcpa_text, consent_at, utm_source, utm_medium, utm_campaign — consent evidence and attribution (see section 5)
Text values are trimmed and whitespace-normalized on the way in: non-breaking spaces (the \u00a0 browser autocomplete often leaves in addresses) become regular spaces, and runs of whitespace collapse to one. Otherwise what you read back is exactly what you sent: an apostrophe or ampersand in a name comes back as typed.
Testing without creating a real lead: add "dry_run": true to the request body. It runs every check — email format, duplicate email, your account’s lead limit, and every fields key — and tells you what would happen, without writing anything or counting against your plan. Useful for a first integration before you trust it with real data.
Example, a motivated seller lead:
curl -X POST https://investorfunnel.com/api/v1/leads \
-H "Authorization: Bearer if_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","firstname":"John","lastname":"Smith","phone":"5551234567","funnel_type":"seller","source":"My Lead Gen Source"}'
A successful call returns 201 with the new lead, including its id. Sending the same email twice returns 409 instead of creating a duplicate, so it is safe to retry a request that timed out.
4. Sending Funnel-Specific Fields
Every funnel type asks for more than name/email/phone — a seller funnel also wants the property address, condition, bed/bath count, asking price, and so on. Send that data in the fields object so it lands in the lead’s record exactly like a visitor filled it out by hand, instead of getting flattened into one notes paragraph.
fields keys must match your account’s actual field set for that funnel_type (your own custom fields, if you have configured any, otherwise the platform defaults). An unknown key is rejected with a 422 that lists the valid keys for that funnel type, rather than being silently dropped — a typo shows up immediately instead of vanishing.
Example, the same seller lead with property details attached:
curl -X POST https://investorfunnel.com/api/v1/leads \
-H "Authorization: Bearer if_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"firstname": "John",
"lastname": "Smith",
"phone": "5551234567",
"funnel_type": "seller",
"source": "My Lead Gen Source",
"fields": {
"address": "123 Main St, Columbus, OH",
"propertytype": "Single Family Home",
"condition": "Needs Rehab",
"bed": "3 Beds",
"bath": "2 Baths",
"price": "150000",
"why": "Relocating for work"
}
}'
Leads created with fields are scored the same way an organic submission is (your account’s lead scoring rules, if any, evaluate the same field names), instead of defaulting to a score of 0.
Not sure which keys your account’s seller (or buyer, investor, lender, provider, apprentice) form actually uses? Send a request with an obviously-wrong key like "fields": {"_": "_"} — the 422 error lists every valid key for that funnel type.
5. Consent Evidence and Attribution
If you buy or generate leads under TCPA rules, send the proof along with the lead so it lives on the lead record instead of in a spreadsheet somewhere else. Every one of these is optional and accepted on both create and update:
ip_address and user_agent — the consumer’s own IP and browser when they submitted, not your server’s. Without ip_address we record the IP the request came from, which is usually your integration, so send it.landing_page_url and referrer_url — the page they converted on and the page that sent them there (http or https).trustedform_cert_url — https://cert.trustedform.com/<token>. We store it as sent; claiming the certificate stays in your own ActiveProspect account (unclaimed certs expire after 72 hours).jornaya_leadid — the Jornaya LeadiD token, UUID format.tcpa_text — the exact consent wording the consumer saw, up to 5,000 characters. Shown on the lead’s Consent & Compliance card.consent_at — when they consented, ISO 8601 such as 2026-09-04T14:03:00Z. Defaults to the moment we receive the lead, which is usually later than the real consent, so send the real one.utm_source, utm_medium, utm_campaign — recorded in attribution reporting alongside your organic funnel traffic.external_id — your own id for the lead. Unique per account: reusing one returns 409 (code: "duplicate_external_id"), and GET .../leads?external_id=... finds the lead by it, so you can update a lead you already sent without storing our id.
Everything you send comes back on GET under the same names, plus consent_source (api_import for API leads).
6. Look Up Leads
GET https://investorfunnel.com/api/v1/leads lists your leads, newest first, filterable by status, funnel_type, and search, with sort, page, and per_page for pagination, or by external_id. GET .../leads?id=123 (or .../leads/123) fetches one lead by ID, including its fields.
7. Update a Lead
PATCH https://investorfunnel.com/api/v1/leads?id=123 or .../leads/123 (requires a Read + Write key) updates only the fields you send: firstname, lastname, phone, source, status, funnel_type, lead_score (0–100), fields (same validation as create — merged into the lead’s existing data, so a partial update cannot wipe out fields set earlier), or any of the consent evidence params from section 5 (an empty string clears one). Moving status to qualified or contacted fires the same automation as changing it by hand in the dashboard.
Errors
Every error returns JSON with an error message. 400 means the request body is not valid JSON (code: "invalid_json"); check for a trailing comma or an unescaped quote. 401 means your key is missing, malformed, or revoked. 403 means your key lacks the required permission, your account is not active, your plan does not include API access, or you have hit your account’s lead limit (code: "limit_reached" in the response). 422 means validation failed — a missing/malformed email, an invalid value against one of your field’s validation rules, or an unrecognized fields key. 409 means that email (or external_id) already exists as a lead in your account. 429 means you hit the rate limit — check the Retry-After header and back off before retrying.
Get Notified When a Lead Comes In
If you have webhooks configured for “new lead,” they fire for API-created leads too, same as any lead captured through a funnel. No extra setup needed on the API side.
Managing Keys
Revoke a key anytime from API Keys in your dashboard — anything using it stops working immediately. You can have up to 10 active keys per account.