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 consent evidence. Structured POST /leads accepts a Leadping Consent certificate ID or a TrustedForm URL. Flat POST /leads/intake currently accepts only a TrustedForm 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 an issued certificate in a field supported by the chosen endpoint.

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.

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:

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, 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": {},
  "tagIds": [],
  "tagNames": ["Partner Website"]
}

For TrustedForm, send the certificate as metadata.trustedFormUrl.

Structured request with Leadping Consent

Replace the illustrative UUID below with an issued certificate for this exact contact and submission. Send this payload to POST /leads, not /leads/intake; use the same source-key header shown above.

{
  "metadata": {
    "externalId": "partner-lead-88391",
    "leadpingConsentCertificateId": "b9dad28d-0756-4e2e-b3c9-b64b31e0f65f"
  },
  "contact": {
    "firstName": "Jordan",
    "lastName": "Example",
    "email": "[e-mail]",
    "phone": { "number": "[phone]" }
  },
  "customer": {},
  "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 before intake. If both certificate fields are present, Leadping validates the Leadping Consent ID first; an invalid ID does not fall back to TrustedForm.

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. A top-level leadpingConsentCertificateId is not mapped; use the structured endpoint for Leadping Consent. 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
TrustedForm certificate	metadata.trustedFormUrl	trustedFormUrl
Leadping Consent certificate	metadata.leadpingConsentCertificateId	Not supported; use POST /leads
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
Both supported certificate fields are missing (or flat intake has no TrustedForm URL)	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 checks the submitted certificate 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 the conversation and intended follow-up separately
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.

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

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, Leadping Consent ID, then TrustedForm URL. 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 [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 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 for the complete generated schemas.