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

# Send an SMS message to an organization lead

> Sends an SMS message to a lead or phone number, applying current-organization sender selection, scheduling, and delivery rules.



## OpenAPI

````yaml /openapi.json post /sms/send
openapi: 3.1.1
info:
  title: Leadping 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
security: []
tags:
  - name: leadping.Api
    description: >-
      Agent-to-agent discovery and request handling for Leadping's supported AI
      agent integrations.
  - name: Analytics
    description: >-
      Provides lead, communication, conversion, and organization performance
      analytics. Use these endpoints to measure activity over time, compare
      outcomes, and power operational dashboards and reporting workflows.
  - name: Automations
    description: >-
      Manages automated lead follow-up workflows and their execution history.
      Use these endpoints to configure SMS automation steps, preview eligible
      leads, run workflows, and inspect individual automation executions.
  - name: BlogArticles
    description: >-
      Provides published Leadping blog content. Use these endpoints to list
      published articles and retrieve an individual article by its public slug.
  - name: Conversations
    description: >-
      Provides lead conversation timelines and inbox-oriented conversation
      views. Use these endpoints to list recent conversations and retrieve the
      cross-channel communication history associated with a lead.
  - name: Feedback
    description: >-
      Captures Leadping product feedback and supports administrative triage.
      Users can submit feedback, while authorized staff can search, inspect,
      classify, and update feedback throughout the review process.
  - 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.
  - name: LeadStatusChanges
    description: >-
      Manages the auditable history of lead status transitions. Use these
      endpoints to change a lead's status, correct transition records, search
      status history, and export status activity for reporting.
  - name: LeadStatuses
    description: >-
      Manages the lead statuses used to classify and track leads throughout
      their lifecycle. Use these endpoints to list, create, update, and archive
      organization-specific lead statuses for consistent pipeline organization
      and reporting.
  - name: Notifications
    description: >-
      Manages user notifications, announcements, and push-notification
      installations. Use these endpoints to retrieve notification feeds and
      unread counts, update read state, and register or remove client push
      installations.
  - name: OutboundDelivery
    description: >-
      Reports outbound delivery pacing and sending capacity for the current
      organization. Use these endpoints to determine whether outbound
      communications can proceed and to understand active throttles, limits, or
      capacity constraints.
  - name: Sources
    description: >-
      Manages lead sources, intake credentials, routing defaults, and
      attribution. Use these endpoints to create and configure sources, search
      source records, inspect source activity, rotate intake access, and remove
      obsolete sources.
  - name: Suppressions
    description: >-
      Manages recipient suppression state for compliant Leadping communication
      workflows. Use these endpoints to check contact eligibility, record or
      release suppressions, and review suppression history before sending
      messages or placing calls.
  - name: Tags
    description: >-
      Manages organization-defined tags for categorizing and routing leads. Use
      these endpoints to list, create, update, and archive reusable tags that
      support lead filtering, automation, assignment, and reporting.
  - name: Users
    description: >-
      Manages the current Leadping user's profile, preferences, setup, and
      account workflows. Use these endpoints to retrieve and update user data,
      configure communication and compliance preferences, complete onboarding,
      manage plan-related actions, and request account operations.
  - name: Calls
    description: >-
      Manages outbound Leadping calls and active call-control workflows. Use
      these endpoints to initiate or cancel a call, retrieve call state, and
      transfer an active call within supported telephony flows.
  - name: PhoneNumbers
    description: >-
      Manages phone-number discovery, purchasing, assignment, configuration, and
      compliance. Use these endpoints to search available numbers, manage owned
      numbers and caller identity, configure messaging or voice behavior, and
      monitor registration and warmup state.
  - 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.
  - name: Telephony
    description: >-
      Provides shared authentication and bootstrap data for Leadping telephony
      clients. Use this endpoint to obtain the scoped credentials and
      configuration required to initialize supported calling experiences.
  - name: Organizations
    description: >-
      Manages Leadping organizations, memberships, invitations, settings, and
      API credentials. Use these endpoints to maintain organization profiles and
      branding, manage members and invitations, configure options, and issue or
      revoke organization API keys.
  - name: UserDataExports
    description: >-
      Creates and delivers user-requested exports of Leadping account data. Use
      these endpoints to request an export, monitor its preparation status, and
      download the completed archive through a time-limited redirect.
  - name: CallEvents
    description: >-
      Provides call event records for auditing, diagnostics, and reporting. Use
      these endpoints to search and inspect lifecycle events emitted as Leadping
      calls are initiated, connected, completed, or fail.
  - name: Events
    description: >-
      Provides a unified record of Leadping activity across communication
      channels. Use these endpoints to retrieve event timelines, search event
      history, inspect event details, and record supported application events.
  - name: SmsEvents
    description: >-
      Provides SMS and MMS event records for delivery tracking and diagnostics.
      Use these endpoints to search and inspect message lifecycle events,
      including outbound delivery updates and inbound messaging activity.
  - name: PaymentMethods
    description: >-
      Manages organization payment methods and billing invoices. Use these
      endpoints to add, confirm, inspect, and remove payment methods or retrieve
      invoices associated with the current organization's billing account.
  - name: Transactions
    description: >-
      Provides organization wallet and billing transaction records. Use these
      endpoints to search transaction history, inspect individual charges or
      credits, review transaction summaries, and issue administrative credits.
  - name: Usage
    description: >-
      Provides billable usage records for Leadping services. Use these endpoints
      to review messaging and calling consumption, inspect usage summaries, and
      reconcile provider activity for an organization.
  - name: Wallets
    description: >-
      Manages organization wallet balances, funding, and credit activity. Use
      these endpoints to inspect wallet state and history, configure wallet
      behavior, add funds, and record credits or adjustments.
externalDocs:
  description: >-
    Leadping API documentation, authentication guide, concepts, and integration
    guidance.
  url: https://leadping.ai/docs/api-reference
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/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.
              example:
                type: about:blank
                title: Bad Request
                status: 400
                detail: The request could not be completed.
        '401':
          description: Authentication credentials are missing or invalid.
          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.
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: The request could not be completed.
        '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.
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: The request could not be completed.
        '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.
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: The request could not be completed.
        '500':
          description: An internal server error occurred.
          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.
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: The request could not be completed.
      security:
        - Bearer: []
components:
  schemas:
    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
    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.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Validation errors keyed by the JSON request field name. Present for
            request validation failures.
        traceId:
          type: string
          description: >-
            Request trace identifier used to correlate this problem with
            Leadping diagnostics.
      description: >-
        Standard problem-details response containing machine-readable and
        human-readable information about an HTTP API error.
    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.
    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.
  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

````