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