Create a lead record from an external source

Creates a source-authenticated lead captured outside Leadping, starting follow-up, routing, and automation from structured lead data.

POST /leads

Create a lead record from an external source

cURL

curl --request POST \
  --url https://api.leadping.ai/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "trustedFormUrl": "<string>",
    "utmSource": "<string>",
    "utmMedium": "<string>",
    "utmCampaign": "<string>",
    "utmTerm": "<string>",
    "utmContent": "<string>",
    "referrer": "<string>",
    "landingPage": "<string>",
    "subId": "<string>",
    "pubId": "<string>",
    "ipAddress": "<string>",
    "userAgent": "<string>",
    "externalId": "<string>",
    "sellerLeadId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "price": 123,
    "directPostPrice": 123,
    "product": "<string>",
    "vertical": "<string>",
    "complianceStatus": "<string>",
    "complianceBlockedReason": "<string>",
    "sourceMetadata": {},
    "origin": "<string>",
    "importBatchId": "<string>",
    "isImported": true,
    "assignedPhoneNumberId": "<string>",
    "smsConsentStatus": "<string>",
    "smsOptedOut": true,
    "smsOptOutAt": "2023-11-07T05:31:56Z",
    "smsOptInAt": "2023-11-07T05:31:56Z",
    "smsHelpRequestedAt": "2023-11-07T05:31:56Z",
    "smsConsentPhoneNumber": "<string>",
    "trustedFormCheckedAt": "2023-11-07T05:31:56Z",
    "userId": "<string>",
    "organizationId": "<string>"
  },
  "contact": {
    "firstName": "<string>",
    "lastName": "<string>",
    "streetAddress": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "province": "<string>",
      "region": "<string>",
      "postalCode": "<string>",
      "country": "<string>",
      "additionalInfo": "<string>"
    },
    "coordinate": {
      "latitude": 123,
      "longitude": 123
    },
    "timeZoneId": "<string>",
    "phone": {
      "phoneIdentityId": "<string>",
      "number": "<string>",
      "type": "<string>"
    },
    "email": "[e-mail]",
    "avatarUrl": "<string>"
  },
  "customer": {
    "height": 123,
    "weight": 123,
    "birthDate": "2023-12-25",
    "income": 123,
    "isHomeowner": true,
    "monthsAtResidence": 123,
    "creditScore": 123,
    "hasBankruptcy": true,
    "numberOfDependents": 123,
    "hasMedicalCondition": true
  },
  "tagIds": [
    "<string>"
  ],
  "tagNames": [
    "<string>"
  ]
}
'

201

{
  "assignedToUserId": "<string>",
  "assignedTo": {
    "id": "<string>",
    "name": "<string>"
  },
  "metadata": {
    "trustedFormUrl": "<string>",
    "utmSource": "<string>",
    "utmMedium": "<string>",
    "utmCampaign": "<string>",
    "utmTerm": "<string>",
    "utmContent": "<string>",
    "referrer": "<string>",
    "landingPage": "<string>",
    "subId": "<string>",
    "pubId": "<string>",
    "ipAddress": "<string>",
    "userAgent": "<string>",
    "externalId": "<string>",
    "sellerLeadId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "price": 123,
    "directPostPrice": 123,
    "product": "<string>",
    "vertical": "<string>",
    "complianceStatus": "<string>",
    "complianceBlockedReason": "<string>",
    "sourceMetadata": {},
    "origin": "<string>",
    "importBatchId": "<string>",
    "isImported": true,
    "assignedPhoneNumberId": "<string>",
    "smsConsentStatus": "<string>",
    "smsOptedOut": true,
    "smsOptOutAt": "2023-11-07T05:31:56Z",
    "smsOptInAt": "2023-11-07T05:31:56Z",
    "smsHelpRequestedAt": "2023-11-07T05:31:56Z",
    "smsConsentPhoneNumber": "<string>",
    "trustedFormCheckedAt": "2023-11-07T05:31:56Z",
    "userId": "<string>",
    "organizationId": "<string>"
  },
  "contact": {
    "firstName": "<string>",
    "lastName": "<string>",
    "streetAddress": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "province": "<string>",
      "region": "<string>",
      "postalCode": "<string>",
      "country": "<string>",
      "additionalInfo": "<string>"
    },
    "coordinate": {
      "latitude": 123,
      "longitude": 123
    },
    "timeZoneId": "<string>",
    "phone": {
      "phoneIdentityId": "<string>",
      "number": "<string>",
      "type": "<string>"
    },
    "email": "[e-mail]",
    "avatarUrl": "<string>"
  },
  "phoneIdentity": {
    "number": "<string>",
    "lookup": {
      "number": "<string>",
      "nationalFormat": "<string>",
      "recordType": "<string>",
      "fraud": "<string>",
      "isValid": true,
      "lineType": "Wireline",
      "carrier": {
        "mobileCountryCode": "<string>",
        "mobileNetworkCode": "<string>",
        "name": "<string>",
        "normalizedCarrier": "<string>",
        "type": "FixedLine",
        "errorCode": "<string>"
      },
      "callerName": {
        "name": "<string>",
        "errorCode": "<string>"
      },
      "portability": {
        "alternativeSpid": "<string>",
        "alternativeCarrierName": "<string>",
        "alternativeCarrierType": "<string>",
        "city": "<string>",
        "lineType": "<string>",
        "localRoutingNumber": "<string>",
        "operatingCompanyNumber": "<string>",
        "portedDate": "<string>",
        "portedStatus": "<string>",
        "spid": "<string>",
        "carrierName": "<string>",
        "carrierType": "<string>",
        "state": "<string>"
      },
      "location": {
        "location": "<string>",
        "state": "<string>",
        "canonicalCity": "<string>",
        "canonicalState": "<string>",
        "countryCode": "<string>",
        "coordinate": {
          "latitude": 123,
          "longitude": 123
        },
        "coordinateSource": {
          "method": "<string>",
          "query": "<string>"
        },
        "timeZoneId": "<string>",
        "timeZoneSource": {
          "method": "<string>",
          "query": "<string>"
        }
      },
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "modifiedAt": "2023-11-07T05:31:56Z"
    },
    "providerEnrichment": {
      "provider": "<string>",
      "lookupType": "<string>",
      "schemaVersion": 123,
      "retrievedAt": "2023-11-07T05:31:56Z",
      "rawRecordJson": "<string>"
    },
    "lastEnrichedAt": "2023-11-07T05:31:56Z",
    "lookupActions": [
      {
        "id": "<string>",
        "type": "validation",
        "provider": "<string>",
        "status": "succeeded",
        "occurredAt": "2023-11-07T05:31:56Z",
        "providerCostAmount": 123,
        "providerPricingVersion": "<string>"
      }
    ],
    "name": "<string>",
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "modifiedAt": "2023-11-07T05:31:56Z"
  },
  "customer": {
    "gender": "M",
    "height": 123,
    "weight": 123,
    "birthDate": "2023-12-25",
    "maritalStatus": "Married",
    "income": 123,
    "isHomeowner": true,
    "monthsAtResidence": 123,
    "creditScore": 123,
    "hasBankruptcy": true,
    "employmentType": "Employed",
    "numberOfDependents": 123,
    "hasMedicalCondition": true
  },
  "enabled": true,
  "deletedAt": "2023-11-07T05:31:56Z",
  "deletedByUserId": "<string>",
  "archivedAt": "2023-11-07T05:31:56Z",
  "archivedByUserId": "<string>",
  "archiveReason": 0,
  "archiveNote": "<string>",
  "isArchived": true,
  "currentLeadStatus": {
    "id": "<string>",
    "category": "Open",
    "outcome": "<string>",
    "displayName": "<string>",
    "changedAt": "2023-11-07T05:31:56Z",
    "changedByUserId": "<string>",
    "changedByAutomationId": "<string>",
    "source": "User"
  },
  "processingStatus": "Quarantined",
  "processingStatusReason": "<string>",
  "processingStatusChangedAt": "2023-11-07T05:31:56Z",
  "tags": [
    {
      "id": "<string>",
      "name": "<string>",
      "normalizedName": "<string>",
      "color": "<string>"
    }
  ],
  "id": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "modifiedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Leadping source key for lead ingestion endpoints only using the Authorization header. Example: "Authorization: Bearer lp_src_...".

Body

application/jsonapplication/*+json

The lead data submitted by the external system.

Defines the fields clients can send when working with lead.

metadata · object · required

Structured metadata used for attribution, integrations, and reporting on this lead request.

Show child attributes

contact · object · required

Contact details for the lead or customer represented by this lead request.

Show child attributes

customer · object · required

Demographic profile details for the lead represented by this lead request.

Show child attributes

tagIds · string[] · required

Tag IDs assigned to or filtered against this lead.

tagNames · string[] · required

Tag names assigned to this lead when matching existing tags by name.

enabled · null | boolean

Indicates whether this lead request is active and available in the Leadping API.

id · null | string

Stable unique identifier of an existing resource to update; omit it when the API assigns an identifier during creation.

Response

201

application/json

Lead was successfully created.

Describes lead data returned by Leadping.

assignedToUserId · null | string

Leadping user currently responsible for this lead, or null when it is in the unassigned queue.

assignedTo · object | null

Identifier and display name of the active organization member assigned to this lead.

Show child attributes

metadata · object

Structured metadata used for attribution, integrations, and reporting on this lead response.

Show child attributes

contact · object

Contact details for the lead or customer represented by this lead response.

Show child attributes

phoneIdentity · object | null

Canonical phone identity and provider lookup details for this lead.

Show child attributes

customer · object

Demographic profile details for the lead represented by this lead response.

Show child attributes

enabled · boolean

Indicates whether this lead response is active and available in the Leadping API.

deletedAt · null | string<date-time>

UTC timestamp when this lead was soft deleted.

deletedByUserId · null | string

User ID of the person who soft deleted this lead.

archivedAt · null | string<date-time>

UTC timestamp when this record was archived.

archivedByUserId · null | string

User ID of the person who archived this record.

archiveReason · null | enum<integer>

Defines why a lead was removed from the active working pipeline.

Available options: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

archiveNote · null | string

Optional note explaining why the lead was archived.

isArchived · boolean

Indicates whether the lead has been archived in Leadping.

currentLeadStatus · object | null

Current lead status change summary that describes the lead outcome.

Show child attributes

processingStatus · null | enum<string>

Defines the asynchronous verification and enrichment lifecycle for a lead.

Available options: Quarantined, Verifying, Validating, Enriching, Ready, Invalid, Failed

processingStatusReason · null | string

Explanation when asynchronous lead processing is blocked or fails.

processingStatusChangedAt · null | string<date-time>

UTC timestamp when the processing stage last changed.

tags · object[]

Tags currently attached to this lead, source, or record.

Show child attributes

id · string

Stable unique identifier of the resource.

createdAt · string<date-time>

UTC timestamp when the resource was created.

modifiedAt · null | string<date-time>

UTC timestamp when the resource was last modified, or null when it has not been updated.