Sending Leads to Leadping

Revision Date: June 28, 2026 Leadping accepts external lead submissions from approved sources. Each accepted lead becomes a traceable record with source context, contact details, consent evidence, metadata, tags, and a conversation your team can work from. Use this guide when you are building or testing a form post, partner post, CRM sync, buyer integration, or internal lead workflow. If the source has not been created and approved yet, start with Lead Sources.

Fast path

For a new integration you control:

Create a separate Leadping source for the real website, partner, form, campaign, or system.
Get the source’s source key.
Send POST /leads with metadata, contact, and customer objects.
Include metadata.trustedFormUrl unless Leadping approved a different evidence path for that source.
Send at least one reachable contact method: phone number or email address.
Test with the real posting system and verify the record, source, tags, TrustedForm URL, conversation, and downstream workflow in Leadping.

Before sending production traffic

Confirm these items first:

The source exists in Leadping.
The source is enabled and approved for production intake.
You have the correct source key for that source.
You know whether the source requires TrustedForm.
The source’s allowed states, products, and tags are configured correctly.
Your payload includes at least one contact method: phone number or email address.
Your team has tested what happens after the lead is accepted.

Do not reuse credentials across unrelated publishers, forms, campaigns, or partners when separate source review would be clearer.

Choose an endpoint

Leadping has two external lead creation paths:

Endpoint	Method	Use it when
`/leads`	`POST`	You control the integration and can send the standard structured payload with `metadata`, `contact`, and `customer` objects
`/leads/intake`	`POST`	You need direct-post compatibility with common flat lead fields
`/leads/intake`	`GET`	A legacy posting system cannot send a JSON body and must send fields in the query string

Use POST /leads for new integrations when you control the payload shape. Use /leads/intake when you need direct-post compatibility. Use query-string intake only when a legacy system cannot send JSON.

Authentication

External lead intake uses a source key instead of a user token or business API key. Send the source key in the Authorization header with the Bearer scheme:

Header	Description
`Authorization: Bearer lp_src_...`	Identifies and authenticates the approved Leadping source

POST https://api.leadping.ai/leads/intake
Authorization: Bearer lp_src_example
Content-Type: application/json

Leadping rejects submissions when the source key is missing or invalid, the source is disabled, or the source is not attached to an account. lp_src_ source keys are only valid for lead ingestion through POST /leads, POST /leads/intake, and GET /leads/intake. They are rejected for account, business, user, analytics, setup, and other non-ingestion API operations. Treat the source key as a secret. Use HTTPS, store it outside source code, and rotate it if it is exposed. Source-key intake is for approved lead submissions. For authenticated account API calls, use the API Reference or SDKs with Authorization: Bearer <leadping_user_access_token> or Authorization: Bearer lp_....

Structured payload

POST /leads expects a structured payload with metadata, contact, and customer objects.

POST https://api.leadping.ai/leads
Authorization: Bearer lp_src_example
Content-Type: application/json

{
  "metadata": {
    "externalId": "partner-lead-88391",
    "sellerLeadId": "seller-4471",
    "utmSource": "partner-website",
    "utmCampaign": "june-campaign",
    "product": "Example product",
    "trustedFormUrl": "https://cert.trustedform.com/example",
    "sourceMetadata": {
      "placement": "homepage-form",
      "publisher": "example-publisher"
    }
  },
  "contact": {
    "firstName": "Jordan",
    "lastName": "Example",
    "email": "jordan@example.com",
    "phone": {
      "number": "+15555550123"
    },
    "streetAddress": {
      "line1": "100 Main St",
      "line2": "Suite 200",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
  },
  "customer": {
    "birthDate": "1970-01-15",
    "gender": "Unknown"
  },
  "tagNames": [
    "Partner Website",
    "June Campaign"
  ]
}

metadata.trustedFormUrl is required for external lead submissions unless Leadping has approved a different intake path for that source.

Flat intake payload

POST /leads/intake accepts common top-level fields and maps them into the structured lead model.

POST https://api.leadping.ai/leads/intake
Authorization: Bearer lp_src_example
Content-Type: application/json

{
  "firstName": "Jordan",
  "lastName": "Example",
  "email": "jordan@example.com",
  "phone": "+15555550123",
  "address1": "100 Main St",
  "address2": "Suite 200",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "birthDate": "1970-01-15",
  "subId": "affiliate-22",
  "sellerLeadId": "seller-4471",
  "price": 18.5,
  "utmSource": "partner-website",
  "utmCampaign": "june-campaign",
  "product": "Example product",
  "vertical": "Example vertical",
  "landingPage": "https://example.com/quote",
  "referrer": "https://example.com",
  "trustedFormUrl": "https://cert.trustedform.com/example",
  "externalId": "partner-lead-88391",
  "sourceMetadata": {
    "placement": "homepage-form"
  },
  "tagNames": [
    "Partner Website",
    "June Campaign"
  ]
}

Flat intake also records the request IP address and user agent when available.

Query-string intake

GET /leads/intake accepts the same flat fields as query string parameters for posting systems that cannot send a JSON body.

GET https://api.leadping.ai/leads/intake?FirstName=Jordan&LastName=Example&Phone=%2B15555550123&TrustedFormUrl=https%3A%2F%2Fcert.trustedform.com%2Fexample
Authorization: Bearer lp_src_example

Prefer POST when your system supports it. Query-string intake can expose more data in logs, browser history, proxy logs, or analytics systems.

Required lead shape

Every accepted external lead must be tied to a valid source and include enough contact, source, and consent context to support follow-up:

Valid source credentials
An enabled source attached to an account
A compliance-approved source
A TrustedForm certificate URL when required
At least one contact method: email address or phone number
A valid email address when email is present
A possible U.S. phone number when phone is present

If the source has allowed states configured, the lead must include a matching state. If the source has allowed products configured, the lead must include a matching product. Leadping may reject, quarantine, delete, pause, or review leads that appear fraudulent, non-consented, unverifiable, inconsistent with the approved source, inconsistent with the submitted TrustedForm certificate, prohibited by policy, or risky to recipients, carriers, providers, Leadping, or the platform.

TrustedForm validation

External lead intake usually requires a TrustedForm certificate URL. Leadping validates that:

A TrustedForm URL is present when required.
The URL is a valid HTTP or HTTPS URL.
The URL is hosted by trustedform.com.
The certificate can be reached and accepted by the TrustedForm validation path.
The source, contact, and campaign context are consistent enough for intake.

For more background, see Requiring TrustedForm.

Source validation

Leadping checks source-level controls before creating the lead:

Check	Failure behavior
Missing source key bearer token	Request is unauthorized
Unknown or wrong source key bearer token	Request is unauthorized
Disabled source	Request is forbidden
Source not attached to an account	Request is forbidden
Source not compliance-approved	Lead validation fails
State not allowed for source	Lead validation fails
Product not allowed for source	Lead validation fails
TrustedForm required but missing	Lead validation fails

What happens after a lead is accepted

When Leadping accepts a lead, it:

Creates the lead record.
Assigns source, account, and business context.
Normalizes the phone number to E.164 where possible.
Attempts phone lookup enrichment where available.
Creates a conversation for the lead.
Records a lead-created event.
Applies source defaults and submitted tags where allowed.
Makes the lead available for inbox, lead detail pages, reporting, calling, SMS, and eligible automations.

A 201 Created response means the submitted payload passed Leadping’s technical and configured source validation. It does not mean the lead is lawful, the recipient consented, a campaign is approved, a message or call may be sent, or a carrier will deliver future traffic. For operations teams, the most important check after a successful post is whether the accepted lead is usable: the source, product, state, tags, TrustedForm URL, phone or email, assignment, and conversation should match what the posting system intended.

Error handling

Use HTTP status codes as the first signal:

Status	Meaning
`201`	Lead was accepted and created
`400`	Payload shape, contact data, source compliance, TrustedForm, state, or product validation failed
`401`	Source credentials are missing or invalid
`403`	Source exists but is disabled or not allowed to accept traffic
`404`	The requested route or referenced record was not found

Do not retry 400, 401, or 403 responses without changing the request or source configuration. Repeating the same invalid request can cause source review or throttling. If a network timeout happens after submission, check whether the lead was created before retrying aggressively. Use stable externalId or sellerLeadId values so your team can trace duplicates and reconcile with the posting system.

Field guidance

Send phone numbers in E.164 format when possible, such as +15555550123.
Send dates as ISO values such as YYYY-MM-DD.
Use stable externalId or sellerLeadId values so records can be traced back to your system.
Use product, vertical, state, and tags consistently with the source configuration.
Put only safe, non-secret values in sourceMetadata; values may be visible in API responses or support workflows.
Keep source-specific classification fields in metadata instead of overloading contact fields.
Never send source keys, API keys, tokens, passwords, or private credentials inside lead metadata.
Keep field names consistent across campaigns. Changing names or formats can break routing, reporting, and source review.

Go-live checklist

Before increasing traffic:

Submit one valid test lead from the real posting system.
Confirm the lead appears under the expected source.
Confirm contact fields, address fields, product, state, tags, and metadata map correctly.
Confirm the TrustedForm URL is present and valid.
Confirm automations, alerts, inbox views, calls, or SMS behave as expected.
Confirm your team has a path for failed posts, disputes, opt-outs, and source changes.

For endpoint schemas, parameters, and response shapes, use the API Reference or the published OpenAPI spec.

Overview

Lead Intake

Readiness & Compliance

API, SDKs & AI

Trust

Legal

Sending Leads to Leadping

Fast path

Before sending production traffic

Choose an endpoint

Authentication

Structured payload

Flat intake payload

Query-string intake

Required lead shape

TrustedForm validation

Source validation

What happens after a lead is accepted

Error handling

Field guidance

Go-live checklist

​Fast path

​Before sending production traffic

​Choose an endpoint

​Authentication

​Structured payload

​Flat intake payload

​Query-string intake

​Required lead shape

​TrustedForm validation

​Source validation

​What happens after a lead is accepted

​Error handling

​Field guidance

​Go-live checklist

Fast path

Before sending production traffic

Choose an endpoint

Authentication

Structured payload

Flat intake payload

Query-string intake

Required lead shape

TrustedForm validation

Source validation

What happens after a lead is accepted

Error handling

Field guidance

Go-live checklist