openapi: 3.2.0
info:
title: Leadping Sms 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: Sms
description: Sends and manages SMS and MMS communications through Leadping. Use these endpoints to send messages, upload MMS media, and cancel eligible scheduled messages while preserving conversation and delivery tracking.
paths:
/sms/send:
post:
tags:
- Sms
summary: Send an SMS message to an organization lead
description: Sends an SMS message to a lead or phone number, applying current-organization sender selection, scheduling, and delivery rules.
operationId: Sms_Send
requestBody:
description: The SMS request containing recipient and message details.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SendSmsRequest'
description: Defines the fields clients can send when working with SMS send.
application/*+json:
schema:
allOf:
- $ref: '#/components/schemas/SendSmsRequest'
description: Defines the fields clients can send when working with SMS send.
required: true
responses:
'201':
description: The sms response was created successfully.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SmsResponse'
description: Describes an SMS or MMS message, including participants, delivery state, scheduling, media, and billing details.
'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.
'500':
description: An internal server error occurred.
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: []
/sms/media:
post:
tags:
- Sms
summary: Upload media for an MMS message
description: Uploads and validates one media attachment, returning the metadata needed to include the asset in a subsequent Leadping MMS send.
operationId: Sms_UploadMedia
requestBody:
description: The image or media file to validate and upload for a subsequent MMS message.
content:
multipart/form-data:
schema:
required:
- file
type: object
properties:
file:
type: string
description: Binary file content to upload.
format: binary
required: true
responses:
'200':
description: OK
content:
text/plain:
schema:
allOf:
- $ref: '#/components/schemas/MessageMediaAttachment'
description: Media attached to an SMS/MMS conversation event.
application/json:
schema:
allOf:
- $ref: '#/components/schemas/MessageMediaAttachment'
description: Media attached to an SMS/MMS conversation event.
text/json:
schema:
allOf:
- $ref: '#/components/schemas/MessageMediaAttachment'
description: Media attached to an SMS/MMS conversation event.
'400':
description: The request was invalid or failed validation.
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.
headers:
WWW-Authenticate:
description: Bearer authentication challenge returned when credentials are missing or invalid.
schema:
type: string
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.
'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: []
/sms/{smsEventId}/cancel:
post:
tags:
- Sms
summary: Cancel a scheduled SMS message for a lead
description: Cancels a scheduled SMS event before delivery, preserving the event record while preventing the queued message from being sent.
operationId: Sms_CancelScheduled
parameters:
- name: smsEventId
in: path
description: The sms event identifier.
required: true
schema:
type: string
responses:
'200':
description: Returns the sms response.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SmsResponse'
description: Describes an SMS or MMS message, including participants, delivery state, scheduling, media, and billing details.
'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.
'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: []
components:
schemas:
CommunicationConsoleEntry:
type: object
properties:
id:
type: string
description: Unique identifier of this diagnostic console entry.
stage:
type: string
description: Communication-processing stage that produced the entry, such as validation, routing, or provider delivery.
status:
type: string
description: Outcome or state recorded for this processing stage.
message:
type: string
description: User-safe diagnostic message describing what occurred at this stage.
occurredAt:
type: string
description: UTC timestamp when this communication-processing event occurred.
format: date-time
description: Describes one durable diagnostic entry from the processing of a communication.
SendSmsRequest:
required:
- conversationId
- text
type: object
properties:
smsEventId:
type:
- 'null'
- string
description: Existing SMS event ID to reuse or update when retrying a send request.
scheduledFor:
type:
- 'null'
- string
description: UTC timestamp when Leadping should send the SMS message.
format: date-time
conversationId:
type: string
description: Conversation ID that links this SMS send request to the Leadping inbox thread.
fromPhoneNumberId:
type:
- 'null'
- string
description: Sender phone number ID used for this outbound SMS or call.
wasManuallyOverridden:
type: boolean
description: Indicates whether a user manually overrode Leadping's automatic number selection for this SMS send request.
campaignId:
type:
- 'null'
- string
description: Messaging campaign identifier associated with this SMS send request.
sourceId:
type:
- 'null'
- string
description: Lead source ID used for attribution and sender selection.
text:
type: string
description: Body text for the SMS message or communication represented by this SMS send request.
mediaUrls:
type: array
items:
type: string
description: Public HTTPS media URLs to attach. Supplying at least one URL sends the message as MMS.
outboundIdempotencyKey:
type:
- 'null'
- string
description: Idempotency key used to prevent duplicate outbound delivery.
description: Defines the fields clients can send when working with SMS send.
example:
conversationId: conversation-123
text: Thanks for your interest. When is a good time to talk?
mediaUrls: []
outboundIdempotencyKey: sms-example-001
MessageMediaAttachment:
type: object
properties:
url:
type: string
description: URL from which the media attachment can be retrieved.
format: uri
contentType:
type:
- 'null'
- string
description: MIME content type of the media attachment.
size:
type:
- 'null'
- integer
description: Size of the media attachment in bytes.
format: int64
sha256:
type:
- 'null'
- string
description: SHA-256 digest of the media content, when available.
fileName:
type:
- 'null'
- string
description: Original file name of the media attachment, when available.
description: Media attached to an SMS/MMS conversation event.
SmsResponse:
type: object
properties:
conversationId:
type: string
description: Conversation ID that links this SMS message to the Leadping inbox thread.
leadId:
type: string
description: Lead ID associated with the SMS conversation or outreach attempt.
fromPhoneNumberId:
type: string
description: Sender phone number ID used for this outbound SMS or call.
outboundPhoneNumberId:
type: string
description: Phone number ID selected for outbound delivery.
fromPhoneNumber:
type:
- 'null'
- string
description: Sender phone number used for this communication.
selectionReason:
enum:
- StickyConversation
- LeadAssigned
- CampaignOrSource
- Preferred
- LocalArea
- HealthyPool
- FallbackDefault
- ManualOverride
type:
- 'null'
- string
description: Explains why Leadping selected, rejected, or substituted an outgoing caller or messaging number.
wasManuallyOverridden:
type: boolean
description: Indicates whether a user manually overrode Leadping's automatic number selection for this SMS message.
campaignId:
type:
- 'null'
- string
description: Messaging campaign identifier associated with this SMS message.
sourceId:
type:
- 'null'
- string
description: Lead source ID used for attribution and sender selection on this SMS message.
text:
type: string
description: Body text for the SMS message or communication represented by this SMS message.
media:
type: array
items:
allOf:
- $ref: '#/components/schemas/MessageMediaAttachment'
description: Media attached to an SMS/MMS conversation event.
description: Media attached to this message. A non-empty collection identifies an MMS message.
status:
enum:
- draft
- scheduled
- queued
- sending
- sent
- received
- delivered
- failed
- undeliverable
- opted_out
- blocked_compliance
- blocked_billing
- blocked_missing_campaign
- canceled
type:
- 'null'
- string
description: Describes the normalized lifecycle of an SMS or MMS message from scheduling through delivery or failure.
statusReason:
type:
- 'null'
- string
description: Human-readable reason explaining the current status of this SMS message.
queuedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping queued this SMS message for processing.
format: date-time
scheduledFor:
type:
- 'null'
- string
description: UTC timestamp when Leadping is scheduled to send this SMS message.
format: date-time
scheduledReason:
type:
- 'null'
- string
description: Reason Leadping scheduled this delivery for a later time.
sendingStartedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping began sending this message.
format: date-time
sentAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping sent this message to the provider.
format: date-time
deliveredAt:
type:
- 'null'
- string
description: UTC timestamp when the provider confirmed delivery.
format: date-time
receivedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping received this inbound event or message.
format: date-time
failedAt:
type:
- 'null'
- string
description: UTC timestamp when processing failed for this SMS message.
format: date-time
undeliverableAt:
type:
- 'null'
- string
description: UTC timestamp when the provider marked the message undeliverable.
format: date-time
blockedAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping blocked this communication.
format: date-time
nextRetryAt:
type:
- 'null'
- string
description: UTC timestamp when Leadping will retry this SMS message.
format: date-time
retryCount:
type: integer
description: Number of retry attempts already made for this SMS message.
format: int32
canceledAt:
type:
- 'null'
- string
description: UTC timestamp when this delivery or workflow was canceled.
format: date-time
cancelReason:
type:
- 'null'
- string
description: Reason this delivery, run, or request was canceled.
errorCode:
type:
- 'null'
- string
description: Machine-readable error code returned while processing this SMS message.
errorMessage:
type:
- 'null'
- string
description: Human-readable error message returned while processing this SMS message.
trafficType:
enum:
- RealLead
- Warmup
- Test
- SystemInternal
- FailedAttempt
type:
- 'null'
- string
description: Classifies messaging traffic by conversational, informational, marketing, or other compliance-relevant purpose.
billableAmount:
type:
- 'null'
- number
description: Monetary amount billed for this Leadping communication or transaction.
format: double
billingStatus:
type:
- 'null'
- string
description: Billing state for this communication, charge, or transaction.
complianceAction:
type:
- 'null'
- string
description: Compliance action applied to this message, lead, or sender.
consoleEntries:
type: array
items:
allOf:
- $ref: '#/components/schemas/CommunicationConsoleEntry'
description: Describes one durable diagnostic entry from the processing of a communication.
description: Ordered diagnostic entries recorded while Leadping processed this message.
id:
type: string
description: Stable unique identifier of the resource.
createdAt:
type: string
description: UTC timestamp when the resource was created.
format: date-time
modifiedAt:
type:
- 'null'
- string
description: UTC timestamp when the resource was last modified, or null when it has not been updated.
format: date-time
description: Describes an SMS or MMS message, including participants, delivery state, scheduling, media, and billing details.
ProblemDetails:
type: object
properties:
type:
type:
- 'null'
- string
description: URI reference that identifies the problem type.
title:
type:
- 'null'
- string
description: Short, human-readable summary of the problem.
status:
type:
- 'null'
- integer
description: HTTP status code returned for the problem.
format: int32
detail:
type:
- 'null'
- string
description: Human-readable explanation specific to this occurrence of the problem.
instance:
type:
- 'null'
- string
description: URI reference that identifies this specific occurrence of the problem.
description: Standard problem-details response containing machine-readable and human-readable information about an HTTP API error.
example:
type: https://leadping.ai/docs/errors/validation
title: Request validation failed
status: 400
detail: One or more request fields are invalid.
instance: /leads/intake
securitySchemes:
Bearer:
type: http
description: Authorization header using the Bearer scheme. Accepted values are Leadping user JWT access tokens and WorkOS organization API keys beginning with sk_.
scheme: bearer
bearerFormat: JWT or organization API key
SourceKey:
type: http
description: 'Leadping source key for lead ingestion endpoints only using the Authorization header. Example: "Authorization: Bearer lp_src_...".'
scheme: bearer
bearerFormat: Leadping source key
externalDocs:
description: Leadping API documentation, authentication guide, concepts, and integration guidance.
url: https://leadping.ai/docs/api-reference