Skip to main content

Documentation Index

Fetch the complete documentation index at: https://leadping.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Leadping accepts external lead submissions from approved sources. A source represents a website, form, buyer, partner, or internal system that is allowed to send leads into a Leadping business. External lead intake uses source credentials instead of a user bearer token.

​
Endpoints

Use this endpoint for the standard structured payload: 
POST https://api.leadping.ai/leads
Content-Type: application/json
X-Leadping-Source-Id: source_123
X-Leadping-Source-Key: lp_source_key
Use this endpoint when your system sends a flatter direct-post payload: 
POST https://api.leadping.ai/leads/intake
Content-Type: application/json
X-Leadping-Source-Id: source_123
X-Leadping-Source-Key: lp_source_key
Both endpoints create a Leadping lead and return 201 Created when validation succeeds.

​
Authentication

Every external submission must include:
HeaderDescription
X-Leadping-Source-IdThe Leadping source ID for the approved source
X-Leadping-Source-KeyThe API key for that source
Leadping rejects submissions when the source ID or key is missing, the source is disabled, the credentials do not match, or the source is not attached to an account.

​
Structured payload

POST /leads expects a structured payload with metadata, contact, and customer objects. 
{
  "metadata": {
    "externalId": "partner-lead-88391",
    "sellerLeadId": "seller-4471",
    "utmSource": "partner-site",
    "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": {
      "address1": "100 Main St",
      "address2": "Suite 200",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    }
  },
  "customer": {
    "birthDate": "1970-01-15",
    "gender": "Unknown"
  }
}

​
Flat intake payload

POST /leads/intake accepts common top-level fields and maps them into the structured lead model. 
{
  "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-site",
  "utmCampaign": "june-campaign",
  "landingPage": "https://example.com/quote",
  "referrer": "https://example.com",
  "trustedFormUrl": "https://cert.trustedform.com/example",
  "externalId": "partner-lead-88391",
  "sourceMetadata": {
    "placement": "homepage-form"
  }
}
Flat intake also records the request IP address and user agent.

​
Required lead shape

Every accepted external lead must include:
  • Valid source credentials
  • An enabled source attached to an account
  • A compliance-approved source
  • A TrustedForm certificate URL
  • A metadata, contact, and customer object after mapping
  • 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.

​
TrustedForm validation

External lead intake requires a TrustedForm certificate URL. Leadping validates that:
  • A TrustedForm URL is present.
  • 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.
For more background, see Requiring TrustedForm.

​
Source validation

Leadping checks source-level controls before creating the lead:
CheckFailure behavior
Missing source ID or API keyRequest is unauthorized
Unknown source or wrong keyRequest is unauthorized
Disabled sourceRequest is forbidden
Source not attached to an accountRequest is forbidden
Source not compliance-approvedLead validation fails
State not allowed for sourceLead validation fails
Product not allowed for sourceLead validation fails
TrustedForm required but missingLead 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.
  • Makes the lead available for inbox, lead detail pages, reporting, calling, SMS, and eligible automations.

​
Error handling

Use HTTP status codes as the first signal:
StatusMeaning
201Lead was accepted and created
400Payload shape, contact data, source compliance, TrustedForm, state, or product validation failed
401Source credentials are missing or invalid
403Source exists but is disabled or not allowed to accept traffic
Do not retry 400, 401, or 403 responses without changing the request or source configuration.

​
Field guidance

  • Use stable externalId or sellerLeadId values so records can be traced back to your system.
  • Put only safe, non-secret values in sourceMetadata.
  • Send phone numbers in E.164 format when possible.
  • Send dates as ISO values such as YYYY-MM-DD.
  • Keep source-specific classification fields in metadata instead of overloading contact fields.
  • Never send API keys, tokens, passwords, or private credentials inside lead metadata.
For endpoint schemas and response shapes, use the API Reference tab.