openapi: 3.2.0
info:
title: Leadping Leads API
description: The Leadping API helps businesses capture and manage leads, automate follow-up, send SMS and MMS messages, place calls, track conversations, enforce contact suppression, and analyze communication workflows. Use this OpenAPI 3.1 contract to integrate lead sources, build organization tools, or generate a typed API client. Authenticate protected operations with a Leadping user access token or WorkOS organization API key. Lead intake operations also accept a Leadping source key.
termsOfService: https://leadping.ai/docs/terms-of-service
contact:
name: Leadping Support
url: https://leadping.ai/contact
email: support@leadping.ai
license:
name: MIT
url: https://opensource.org/licenses/MIT
version: v1
summary: Lead management, messaging, calling, and automation API
servers:
- url: https://api.leadping.ai
description: Production
tags:
- name: Leads
description: Manages lead intake, records, assignment, routing, and lifecycle operations. Use these endpoints to ingest leads from trusted sources, search and update lead records, manage ownership and tags, and archive or delete leads.
paths:
/leads:
post:
tags:
- Leads
summary: Create a lead record from an external source
description: Creates a source-authenticated lead captured outside Leadping, starting follow-up, routing, and automation from structured lead data.
operationId: Leads_CreateExternal
requestBody:
description: The lead data submitted by the external system.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadRequest'
description: Defines the fields clients can send when working with lead.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/LeadRequest'
description: Defines the fields clients can send when working with lead.
required: true
responses:
'201':
description: Lead was successfully created.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'404':
description: A related resource was not found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'400':
description: The request was invalid or malformed.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Source credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The source is not allowed to accept traffic.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- SourceKey: []
/leads/intake:
post:
tags:
- Leads
summary: Create a lead record from intake payload
description: Creates a source-authenticated lead from a flat intake payload, capturing contact fields, metadata, and automation-ready lead details.
operationId: Leads_CreateIntake
requestBody:
description: The common lead fields submitted by the external system.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadIntakeRequest'
description: Defines the fields clients can send when working with lead intake.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/LeadIntakeRequest'
description: Defines the fields clients can send when working with lead intake.
required: true
responses:
'201':
description: The lead response was created successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'400':
description: The request was invalid or failed validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Source credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The source is not allowed to accept traffic.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- SourceKey: []
get:
tags:
- Leads
summary: Create a lead record from query intake
description: Creates a source-authenticated lead from query parameters, supporting simple form posts, tracking metadata, and follow-up automation.
operationId: Leads_CreateIntakeFromQuery
parameters:
- name: FirstName
in: query
description: First name of the lead, user, or contact represented by this lead intake request.
schema:
type: string
- name: LastName
in: query
description: Last name of the lead, user, or contact represented by this lead intake request.
schema:
type: string
- name: Email
in: query
description: Email address for the person represented by this lead intake request.
schema:
type: string
- name: Phone
in: query
description: Phone details for the lead, user, or organization represented by this lead intake request.
schema:
type: string
- name: PhoneType
in: query
description: Source-provided phone type, such as mobile, landline, or VoIP, used during lead intake normalization.
schema:
type: string
- name: DateOfBirth
in: query
description: Lead date of birth supplied by intake sources and normalized into the lead profile.
schema:
type: string
format: date
- name: BirthDate
in: query
description: Lead birth date used for demographic matching and insurance intake workflows.
schema:
type: string
format: date
- name: Address1
in: query
description: First street address line submitted by the lead intake source.
schema:
type: string
- name: Address2
in: query
description: Second street address line submitted by the lead intake source.
schema:
type: string
- name: City
in: query
description: City for the lead or organization postal address.
schema:
type: string
- name: State
in: query
description: State, province, or region for the lead or organization postal address.
schema:
type: string
- name: Zip
in: query
description: ZIP code submitted by the lead intake source.
schema:
type: string
- name: PostalCode
in: query
description: Postal code for the lead or organization address.
schema:
type: string
- name: Gender
in: query
description: Lead gender supplied by intake sources and normalized when possible.
schema:
type: string
- name: SubId
in: query
description: Affiliate or publisher sub ID captured for lead attribution.
schema:
type: string
- name: SellerLeadId
in: query
description: Seller-provided lead identifier used to deduplicate and reconcile lead delivery.
schema:
type: string
- name: SellerLeadIdentifier
in: query
description: Alternate seller-provided lead identifier used during intake normalization.
schema:
type: string
- name: DirectPostPrice
in: query
description: Direct-post price supplied by the lead source during intake.
schema:
type:
- 'null'
- number
format: double
- name: Price
in: query
description: Lead price or transaction price supplied to the Leadping API.
schema:
type:
- 'null'
- number
format: double
- name: UtmSource
in: query
description: UTM source parameter captured for lead attribution reporting.
schema:
type: string
- name: UtmMedium
in: query
description: UTM medium parameter captured for lead attribution reporting.
schema:
type: string
- name: UtmCampaign
in: query
description: UTM campaign parameter captured for lead attribution reporting.
schema:
type: string
- name: UtmTerm
in: query
description: UTM term parameter captured for lead attribution reporting.
schema:
type: string
- name: UtmContent
in: query
description: UTM content parameter captured for lead attribution reporting.
schema:
type: string
- name: Product
in: query
description: Product or offer associated with the lead or source.
schema:
type: string
- name: Vertical
in: query
description: Industry vertical used for lead routing, compliance review, and reporting.
schema:
type: string
- name: Referrer
in: query
description: Referring page or traffic source that sent the lead into Leadping.
schema:
type: string
- name: LandingPage
in: query
description: Landing page URL where the lead submitted their information.
schema:
type: string
- name: TrustedFormUrl
in: query
description: TrustedForm certificate URL used as proof of consumer consent.
schema:
type: string
- name: ExternalId
in: query
description: External system identifier used to reconcile this lead intake request across integrations.
schema:
type: string
- name: SourceMetadata
in: query
description: Source-provided key-value metadata retained for lead attribution and integration troubleshooting.
schema:
type: object
additionalProperties:
type: string
- name: TagIds
in: query
description: Tag IDs assigned to or filtered against this lead.
schema:
type: array
items:
type: string
- name: TagNames
in: query
description: Tag names assigned to this lead when matching existing tags by name.
schema:
type: array
items:
type: string
responses:
'201':
description: The lead response was created successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'400':
description: The request was invalid or failed validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Source credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The source is not allowed to accept traffic.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- SourceKey: []
/leads/{id}:
get:
tags:
- Leads
summary: Get an organization lead record for current user
description: Returns one lead visible to the current user, including communication details, status, source, and follow-up context.
operationId: Leads_GetForCurrentUser
parameters:
- name: id
in: path
description: The ID of the lead to retrieve.
required: true
schema:
type: string
responses:
'200':
description: Lead was successfully retrieved.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'404':
description: The specified lead was not found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: The user does not own this lead.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
put:
tags:
- Leads
summary: Update an organization lead record and status
description: Updates lead details for the current organization, keeping contact data, status, source, and follow-up context current.
operationId: Leads_Update
parameters:
- name: id
in: path
description: The ID of the lead to update.
required: true
schema:
type: string
requestBody:
description: The updated lead data.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadRequest'
description: Defines the fields clients can send when working with lead.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/LeadRequest'
description: Defines the fields clients can send when working with lead.
required: true
responses:
'200':
description: Lead was successfully updated.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'404':
description: The specified lead was not found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'400':
description: The request was invalid or malformed.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
delete:
tags:
- Leads
summary: Delete an organization lead record by ID
description: 'Marks a lead as deleted so it no longer appears in user-facing lead, conversation, routing, or event workflows. The stored lead,
conversation, and event records are retained.'
operationId: Leads_Delete
parameters:
- name: id
in: path
description: The ID of the lead to delete.
required: true
schema:
type: string
responses:
'204':
description: Lead was successfully deleted.
'404':
description: The specified lead was not found.
content:
text/plain:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
text/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
text/plain:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
text/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/leads/{id}/workflow-status:
get:
tags:
- Leads
summary: Get a lead automation workflow status
description: Returns automation workflow status for one lead, including active runs, paused state, and follow-up progress for the current organization.
operationId: Leads_GetWorkflowStatusForCurrentUser
parameters:
- name: id
in: path
description: The unique identifier of the lead whose workflow status to retrieve.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AutomationWorkflowStatusResponse'
description: Automation workflow status collection for a lead.
'404':
description: The requested resource was not found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/leads/{id}/archive:
post:
tags:
- Leads
summary: Archive an organization lead record by ID
description: Archives a lead without deleting history, removing it from active pipeline views while preserving communication and event records.
operationId: Leads_Archive
parameters:
- name: id
in: path
description: The unique identifier of the lead to archive.
required: true
schema:
type: string
requestBody:
description: Optional archive reason and related audit context.
content:
application/json:
schema:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/LeadArchiveRequest'
description: Defines the fields clients can send when working with lead archive.
application/*+json:
schema:
type:
- 'null'
- object
allOf:
- $ref: '#/components/schemas/LeadArchiveRequest'
description: Defines the fields clients can send when working with lead archive.
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/LeadResponse'
description: Describes lead data returned by Leadping.
'404':
description: The requested resource was not found.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'400':
description: The request was invalid or failed validation.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'401':
description: Authentication credentials are missing or invalid.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'403':
description: The authenticated user or organization does not have permission to perform this operation.
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
'429':
description: The API rate limit for this account or client has been exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
minimum: 0
type: integer
format: int32
content:
application/problem+json:
schema:
allOf:
- $ref: '#/components/schemas/ProblemDetails'
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
security:
- Bearer: []
/leads/{id}/unarchive:
post:
tags:
- Leads
summary: Unarchive an organization lead record by ID
description: Restores an archived lead to active pipeline views so follow-up, communication, and routing workflows can resume.
operationId: Leads_Unarchive
parameters:
- name: id
in: path
description: The unique identifier of the archived lead to restore.
required: true
schema:
t
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leadping/refs/heads/main/openapi/leadping-leads-api-openapi.yml