> ## 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 either supported consent evidence or an explicit Other attestation. Both accept Leadping and TrustedForm certificate URLs. Other consent permits manual SMS only after processing; Leadping policy blocks automated outreach. See [Consent](https://leadping.ai/docs/requiring-trustedform.md).

## 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 supported certificate or explicit Other consent attestation, subject to the source's certificate requirement.

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

## Send a first request

Save a flat payload as `lead.json` using the example below. Replace the contact details with a contact you control and the certificate placeholder with the URL captured from that person’s test submission. The example certificate and phone number are illustrative; they are not test credentials or a working certificate.

Set `LEADPING_SOURCE_KEY` in your shell from protected configuration, then run:

```bash theme={null}
curl --request POST 'https://api.leadping.ai/leads/intake' \
  --header "Authorization: Bearer $LEADPING_SOURCE_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @lead.json \
  --include
```

This command uses Bash syntax. In PowerShell, use `curl.exe` and `$env:LEADPING_SOURCE_KEY` for the environment variable.

The request creates a production lead and may start configured automations. Review those automations before sending. Keep the response’s `id` and the `Location` header with the upstream submission record; you will need them to investigate processing or an uncertain retry.

## Structured request

`POST /leads` accepts `metadata` and `contact` objects:

```json theme={null}
{
  "metadata": {
    "externalId": "partner-lead-88391",
    "sellerLeadId": "seller-4471",
    "product": "Example product",
    "utmSource": "partner-website",
    "consentCertificateType": "TrustedForm",
    "consentCertificateUrl": "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"
    }
  },
  "tagIds": [],
  "tagNames": ["Partner Website"]
}
```

For TrustedForm, send the certificate as `metadata.consentCertificateUrl` with `metadata.consentCertificateType` set to `TrustedForm`.

### Structured request with Leadping Consent

Replace the illustrative UUID below with an **issued** certificate for this exact contact and submission. Send this structured payload to `POST /leads`; use the same source-key header shown above. Flat intake accepts the same consent URL and type as top-level fields.

```json theme={null}
{
  "metadata": {
    "externalId": "partner-lead-88391",
    "consentCertificateType": "Leadping",
    "consentCertificateUrl": "https://certificate.leadping.ai/b9dad28d-0756-4e2e-b3c9-b64b31e0f65f"
  },
  "contact": {
    "firstName": "Jordan",
    "lastName": "Example",
    "email": "jordan@example.com",
    "phone": { "number": "+15555550123" }
  },
  "tagIds": [],
  "tagNames": []
}
```

Save it as `lead.json` and change the curl URL to `https://api.leadping.ai/leads`. A Profile onboarding certificate is not evidence for this lead. A capture reference or a `202` issuance response is not ready evidence: [wait for issuance](https://leadping.ai/docs/requiring-trustedform.md#add-consent) before intake. Use one certificate URL and its matching provider type; there is no fallback to another provider on failure.

## 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",
  "consentCertificateType": "TrustedForm",
  "consentCertificateUrl": "https://cert.trustedform.com/example",
  "externalId": "partner-lead-88391",
  "sourceMetadata": {
    "placement": "homepage-form"
  },
  "tagNames": ["Partner Website"]
}
```

For this endpoint, send `consentCertificateUrl` and the matching `consentCertificateType` (`Leadping` or `TrustedForm`). For Other, send `consentCertificateType: "Other"` and `consentAttested: true` with no certificate URL. See the [Other consent example](https://leadping.ai/docs/requiring-trustedform.md#other-consent-example). Leadping also records the request IP address and user agent when available.

## Map fields deliberately

| Information | Structured request | Flat request |
| - | - | - |
| Email | `contact.email` | `email` |
| Phone | `contact.phone.number` | `phone` |
| Your record ID | `metadata.externalId` | `externalId` |
| Seller’s record ID | `metadata.sellerLeadId` | `sellerLeadId` |
| Certificate URL (Leadping or TrustedForm) | `metadata.consentCertificateUrl` | `consentCertificateUrl` |
| Consent source type | `metadata.consentCertificateType` | `consentCertificateType` |
| Other consent attestation | `metadata.consentAttested` | `consentAttested` |
| Campaign attribution | `metadata.utmCampaign` | `utmCampaign` |
| Additional attribution | `metadata.sourceMetadata` | `sourceMetadata` |
| Tag names | `tagNames` | `tagNames` |

Keep postal codes and identifiers as strings so leading zeros survive. `sourceMetadata` values are strings: send a short code or label instead of a nested object. Omit optional fields you do not collect rather than filling them with invented values.

`tagNames` matches organization tags and can create missing names. Agree on a fixed vocabulary with the sender; a typo can create a separate tag instead of applying the intended one. Use `tagIds` when the integration already knows the existing organization tag IDs.

The flat endpoint records the posting request’s IP address and user agent when available. If your server submits the request, those values describe the server request; do not mistake them for the consumer’s browser or location.

## 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` |
| Neither a certificate URL nor an explicit Other attestation is supplied | `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 was created. It can remain in a processing state before the conversation and follow-up become available. Do not resubmit a lead merely because its conversation has not appeared yet.

Leadping evaluates the submitted consent and processes the lead asynchronously. A lead that passes processing moves to **Ready**. Use the returned processing status and reason to decide what to do next; do not try to reproduce Leadping’s validation logic in your integration.

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

| Processing status | What to do |
| - | - |
| **Quarantined**, **Verifying**, **Validating**, or **Enriching** | Keep the created record ID and allow processing to finish; do not treat these as business outcomes |
| **Ready** | Inspect consent verification and the intended follow-up separately; Unverified consent allows manual SMS only |
| **Invalid** | Read `processingStatusReason` and investigate the submitted data or evidence |
| **Failed** | Preserve the lead ID and reason for investigation; avoid creating a replacement without reconciling the original |

If processing does not progress, provide support with the lead ID, submission time, current status, and reason. There is no need to send the full payload or certificate in the initial support request.

> [!NOTE]
>
> 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` | Check the source and account status; resolve the returned reason before resuming |
| `404` | Correct the route or referenced identifier |
| `409` | Read the conflict reason; reconcile the original submission and contact before retrying |
| `429` | Wait according to [rate-limit guidance](https://leadping.ai/docs/rate-limits.md) |

A timeout or lost response leaves the outcome uncertain: the server may have created the lead before the connection failed. Mark the submission as **outcome unknown** in your system and reconcile it before resending. A `5xx` response also warrants checking for a created record before repeating a write.

Keep the same contact, certificate, and submission identifiers when investigating or retrying. Source intake chooses a deduplication key in this order: explicit `metadata.intakeIdempotencyKey` (`idempotencyKey` for flat intake), `sellerLeadId`, the consent certificate URL. Other submissions must supply an explicit idempotency key or seller lead ID. `externalId` alone is a reconciliation field. Reusing a deduplication key for a different contact is rejected; do not change keys to force a second record. Prevent simultaneous retries by giving one worker ownership of each queued submission.

Source keys cannot read leads. Reconcile through the Leadping interface or a separate organization-authorized service. After a confirmed creation, that service can use `GET /leads/{id}` to inspect `processingStatus` and `processingStatusReason`. Do not give the source’s posting system broader credentials solely to check a result.

## 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 the selected certificate 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](https://leadping.ai/docs/api-reference.md) for the complete generated schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.