Leadping Sms API

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/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.
        '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.
        '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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - physical
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
        reversibility:
          supported: conditional
          operation-id: Sms_CancelScheduled
          window: While the SMS status is Scheduled and before delivery begins.
  /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:
            application/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:
            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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - physical
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
  /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.

        The cancellation window remains open only while the SMS status is Scheduled and closes when delivery begins.'
      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/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.
        '404':
          description: The requested resource was not found.
          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: Not Found
                status: 404
                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.
      security:
      - Bearer: []
      x-agentic-access:
        action-class: acting
        consequences:
        - physical
        subject:
          required: true
        authorization:
          source: OpenAPI security requirements
          audience: https://api.leadping.ai
        audit:
          recommended: true
components:
  schemas:
    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.
    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.
    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
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type:
          - 'null'
          - string
          format: date-time
      description: Describes an SMS or MMS message, including participants, delivery state, scheduling, media, and billing details.
    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
    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
    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