> ## 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.

# Sending Leads to Leadping

> Post leads from approved sources to Leadping with source credentials, structured payloads, flat intake, TrustedForm, validation, and error handling.

*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](/lead-sources).

## Fast path

For a new integration you control:

1. Create a separate Leadping source for the real website, partner, form, campaign, or system.
2. Get the source's source key.
3. Send `POST /leads` with `metadata`, `contact`, and `customer` objects.
4. Include `metadata.trustedFormUrl` unless Leadping approved a different evidence path for that source.
5. Send at least one reachable contact method: phone number or email address.
6. 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 |

```http theme={null}
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](/api-reference) or [SDKs](/sdks/overview) 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.

```http theme={null}
POST https://api.leadping.ai/leads
Authorization: Bearer lp_src_example
Content-Type: application/json
```

```json theme={null}
{
  "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.

```http theme={null}
POST https://api.leadping.ai/leads/intake
Authorization: Bearer lp_src_example
Content-Type: application/json
```

```json theme={null}
{
  "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.

```http theme={null}
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](/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](https://leadping.ai/docs/api-reference) or the published [OpenAPI spec](https://leadping.ai/docs/openapi.json).