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

# Require TrustedForm for External Leads

> Submit a TrustedForm certificate URL with every external lead and understand Leadping validation states.

Every external lead sent to Leadping requires its own TrustedForm certificate URL.

<Warning>
  **No certificate, no lead.** Leadping rejects an external intake request when the TrustedForm URL is missing.
</Warning>

## Add the certificate field

| Endpoint             | Required field            |
| -------------------- | ------------------------- |
| `POST /leads`        | `metadata.trustedFormUrl` |
| `POST /leads/intake` | `trustedFormUrl`          |

### Structured request

```json theme={null}
{
  "metadata": {
    "trustedFormUrl": "https://cert.trustedform.com/example"
  },
  "contact": {
    "firstName": "Jordan",
    "phone": {
      "number": "+15555550123"
    }
  },
  "customer": {}
}
```

### Flat request

```json theme={null}
{
  "firstName": "Jordan",
  "phone": "+15555550123",
  "trustedFormUrl": "https://cert.trustedform.com/example"
}
```

Leadping does not provide a GET or query-string intake endpoint.

## What Leadping validates

Lead creation and certificate validation happen in two stages.

### During intake

Leadping confirms that the TrustedForm field is present. A missing value returns `400 Bad Request`, and no lead is created.

### After creation

A successfully created lead begins in **Verifying**. Leadping checks that the certificate URL:

* is an absolute HTTP or HTTPS URL;
* uses `trustedform.com` or one of its subdomains; and
* returns `200 OK` when Leadping requests it.

If those checks pass, Leadping records `trustedFormCheckedAt` and continues processing the lead toward **Ready**.

If they fail, the lead moves to **Invalid** and its processing-status reason describes the failure.

<Note>
  `201 Created` means the lead passed immediate intake validation. It does not mean TrustedForm verification has finished. Check the lead's processing status before treating it as ready.
</Note>

## Integration requirements

* Capture a unique certificate for each lead at the opt-in form.
* Carry the complete URL through every form, webhook, CRM, and posting step.
* Do not substitute a landing page, screenshot, consent timestamp, or internal ID.
* Keep retries associated with the same lead and certificate.
* Confirm a production-path test reaches **Ready** in Leadping.

TrustedForm records the opt-in event. It does not override an opt-out, correct inadequate consent language, or make an otherwise unlawful contact permissible.

## Troubleshoot validation

| Result                    | Cause                                          | Correction                                         |
| ------------------------- | ---------------------------------------------- | -------------------------------------------------- |
| Intake returns `400`      | Certificate field is missing                   | Restore the field mapping before retrying          |
| Lead becomes **Invalid**  | URL is malformed or incomplete                 | Submit the complete certificate URL                |
| Lead becomes **Invalid**  | URL is not hosted on `trustedform.com`         | Submit the URL issued by TrustedForm               |
| Lead becomes **Invalid**  | Certificate URL cannot be reached successfully | Check certificate capture and availability         |
| Wrong certificate appears | A handoff reused or replaced the value         | Preserve the certificate associated with that lead |

Fix the underlying integration before sending more traffic.

## Retention

TrustedForm certificates can expire unless retention is extended. Assign responsibility for retention before production traffic begins, and preserve certificates and related source records for applicable legal, contractual, carrier, audit, and dispute requirements.

<CardGroup cols={2}>
  <Card title="Configure the source" icon="filter" href="/docs/lead-sources">
    Create the intake identity and obtain its source key.
  </Card>

  <Card title="Send leads" icon="paper-plane" href="/docs/sending-leads-to-leadping">
    Build requests and handle processing results.
  </Card>
</CardGroup>