Send Leads with the Intake API

Use a Leadping source key to submit structured or flat leads and handle validation and processing states.

Leadping provides two POST endpoints for external lead intake. Both require a valid, enabled source key and a TrustedForm certificate URL.

Choose an endpoint

Endpoint	Use when
POST /leads	You can send the structured Leadping model
POST /leads/intake	Your form, partner, or CRM sends common flat fields

There is no GET or query-string intake endpoint.

Before sending a lead

Confirm that:

• the source is enabled;
• its lp_src_... key is configured in the posting system;
• the organization can receive billed leads;
• the payload contains a valid email address or U.S. phone number; and
• the payload includes a TrustedForm certificate URL.

Authenticate

Send the source key in the Authorization header:

Authorization: Bearer lp_src_example

For example:

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

The key identifies the source and associates the created lead with its organization. It cannot access account, organization, analytics, or other non-intake operations.

Structured request

POST /leads accepts metadata, contact, and customer objects:

{
  "metadata": {
    "externalId": "partner-lead-88391",
    "sellerLeadId": "seller-4471",
    "product": "Example product",
    "utmSource": "partner-website",
    "trustedFormUrl": "https://cert.trustedform.com/example",
    "sourceMetadata": {
      "placement": "homepage-form"
    }
  },
  "contact": {
    "firstName": "Jordan",
    "lastName": "Example",
    "email": "[e-mail]",
    "phone": {
      "number": "[phone]"
    },
    "streetAddress": {
      "line1": "100 Main St",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
  },
  "customer": {},
  "tagNames": ["Partner Website"]
}

For this endpoint, send the certificate as metadata.trustedFormUrl.

Flat request

POST /leads/intake maps common top-level fields into the Leadping model:

{
  "firstName": "Jordan",
  "lastName": "Example",
  "email": "[e-mail]",
  "phone": "[phone]",
  "address1": "100 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "sellerLeadId": "seller-4471",
  "product": "Example product",
  "landingPage": "https://example.com/quote",
  "trustedFormUrl": "https://cert.trustedform.com/example",
  "externalId": "partner-lead-88391",
  "sourceMetadata": {
    "placement": "homepage-form"
  },
  "tagNames": ["Partner Website"]
}

For this endpoint, send the certificate as trustedFormUrl. Leadping also records the request IP address and user agent when available.

Immediate validation

Leadping validates the source and lead shape before creating the record:

Condition	Response
Source key is missing or invalid	401 Unauthorized
Source is disabled or not attached to an account	403 Forbidden
Lead body, email, or phone is invalid	400 Bad Request
Email and phone are both missing	400 Bad Request
TrustedForm URL is missing	400 Bad Request
Organization cannot receive the lead	Request fails with the returned problem detail
Request passes immediate validation	201 Created

Do not retry 400, 401, or 403 responses until the request, credential, source, or account condition has changed.

Background processing

A 201 Created response means the lead record and conversation were created. The lead begins in Verifying while Leadping processes it.

Leadping then validates that the TrustedForm value is an absolute HTTP or HTTPS URL on trustedform.com or one of its subdomains and that the certificate can be reached successfully. A lead that passes processing moves to Ready.

If TrustedForm validation fails, the lead moves to Invalid with a processing-status reason. A 201 response does not mean background validation has completed.

Technical validation does not establish lawful contact, carrier approval, message delivery, or call completion.

Handle errors and retries

Status	Action
400	Correct the payload or account condition before retrying
401	Replace the missing or invalid source key
403	Enable the source or correct its account attachment
404	Correct the route or referenced identifier
429	Wait according to rate-limit guidance

After a network timeout, check whether the lead was created before retrying. Stable externalId or sellerLeadId values make duplicates easier to find and reconcile.

Field practices

• Format phone numbers as E.164, such as [phone].
• Format dates as YYYY-MM-DD.
• Use stable external IDs for reconciliation.
• Keep sourceMetadata to 20 or fewer non-secret operational fields.
• Never include source keys, API keys, tokens, or passwords in lead fields.
• Keep field names and formats stable across integrations.

Go-live checklist

• Submit a lead from the real production posting system.
• Confirm it appears under the expected source.
• Verify contact, address, tags, metadata, and TrustedForm mapping.
• Wait for the processing status to become Ready.
• Verify the conversation and intended workflow behavior.
• Establish owners for failed posts, invalid leads, duplicates, and source-key rotation.

Use the API Reference for the complete generated schemas.