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

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

```http theme={null}
Authorization: Bearer lp_src_example
```

For example:

```http theme={null}
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:

```json theme={null}
{
  "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": "jordan@example.com",
    "phone": {
      "number": "+15555550123"
    },
    "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:

```json theme={null}
{
  "firstName": "Jordan",
  "lastName": "Example",
  "email": "jordan@example.com",
  "phone": "+15555550123",
  "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.

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

## 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](/docs/rate-limits)    |

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 `+15555550123`.
* 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](/docs/api-reference) for the complete generated schemas.