SimpleVoIP SMS API

openapi: 3.2.0
info:
  title: Simplevoip SMS API
  version: 1.6.0
  license:
    name: Proprietary
  description: 'Operations tagged SMS across 2 of this provider''s published API definitions: simplevoip.json, simplevoip-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public.simplevoip.us
tags:
- name: SMS
  description: Programmatic SMS/MMS sending and inbound/outbound notification webhooks.
paths:
  /sms/send:
    post:
      tags:
      - SMS
      operationId: sendSms
      summary: Send SMS
      description: 'SimpleVoIP supports programmatically sending SMS/MMS messages from any SMS-enabled number registered to your account. Can be used with the SMS Notification Webhook to embed SMS messaging in your own portal or POS system.


        For more detailed info: https://support.simplevoip.com/hc/en-us/articles/13407477118103-Outbound-SMS-API


        A 200 response does not always mean the message was sent — check the `status` field. Business-logic failures (invalid number, unauthorized sender, carrier delivery failure) are returned with HTTP 200 and `"status": "failed"`. Only a missing/invalid authentication method returns a non-200 status (401).'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsRequest'
            examples:
              plainSms:
                summary: Plain SMS
                value:
                  sender: '+15555555555'
                  recipients:
                  - '+15555555556'
                  body_text: Your bearer token auth is working!
              mms:
                summary: MMS with subject and media
                value:
                  sender: '+15555555555'
                  recipients:
                  - '+15555555556'
                  body_text: Here's the photo you asked for.
                  subject: Your requested photo
                  media:
                  - https://example.com/photo.jpg
      responses:
        '200':
          description: Request was processed. Check `status` — a 200 does not guarantee the message was actually sent; see the failure examples below.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SendSmsResponseSuccess'
                - $ref: '#/components/schemas/SendSmsResponseFailure'
              examples:
                success:
                  summary: Success
                  value:
                    status: success
                    msg_id: 550e8400-e29b-41d4-a716-446655440000
                invalidNumber:
                  summary: Invalid sender or recipient number
                  value:
                    status: failed
                    error: Invalid sender or recipient number provided.
                unauthorizedNumber:
                  summary: Sender number not authorized for this account
                  value:
                    status: failed
                    error: You have not been authorized to send SMSes from this number. Please contact SimpleVoIP support for authorization.
                deliveryFailure:
                  summary: Carrier delivery failure
                  value:
                    status: failed
                    error: We encountered an error when trying to deliver your SMS.
        '401':
          description: Missing/invalid bearer token and not on the IP allowlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSmsResponseFailure'
              examples:
                unauthorizedEndpoint:
                  value:
                    status: failed
                    error: You have not been authorized to send via this endpoint. Please contact SimpleVoIP support for authorization.
    servers:
    - url: https://public.simplevoip.us
webhooks:
  smsNotification:
    post:
      tags:
      - SMS
      operationId: smsNotificationWebhook
      summary: SMS Notification Webhook
      security: []
      description: 'Each individual SMS subscriber can be configured to trigger webhook notifications on received and/or sent SMS/MMS messages (`recv_webhook_url` and `send_webhook_url` respectively, configured per subscriber). This webhook is POSTed to the URL you specify, using the JSON format shown below. It fires with an **identical payload shape for both directions** — there is no `direction` field distinguishing an inbound-received notification from an outbound-sent notification; which URL received the POST tells you which event occurred.


        No response body is expected back from your endpoint; only the HTTP status code is used for delivery bookkeeping. There is no retry on failure, and no signature/HMAC header is sent with these requests — treat the source URL as the only verification available today.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsWebhookPayload'
            examples:
              received:
                value:
                  sender: '+12025557979'
                  sender_name: JOHN DOE
                  subscriber_id: '+15775554434'
                  recipients:
                  - '+15775554434'
                  body_text: Hi, got your message, will follow up by EOD today!
                  site_number: '4321'
                  received_time: '2023-03-04 14:51:23-06:00'
                  mediaUrls: []
                  media_ids: []
      responses:
        '200':
          description: Any 2xx response is treated as successful delivery for bookkeeping purposes; the response body itself is not read.
    servers:
    - url: https://public.simplevoip.us
components:
  schemas:
    SmsWebhookPayload:
      type: object
      required:
      - sender
      - sender_name
      - subscriber_id
      - recipients
      - body_text
      - site_number
      - received_time
      - mediaUrls
      - media_ids
      properties:
        sender:
          type: string
          description: The message sender, in E.164 format for a standard number, or as-is for a short code sender.
        sender_name:
          type:
          - string
          - 'null'
          description: CNAM caller-ID name for `sender`, if a lookup has been performed and a name is available; `null` otherwise.
        subscriber_id:
          type: string
          description: The SMS-enabled subscriber number this webhook is configured against, in the same format as `sender`.
        recipients:
          type: array
          items:
            type: string
          description: E.164 destination number(s).
        body_text:
          type: string
          description: Message body.
        site_number:
          type: string
          description: Site number associated with the subscriber's linked location. Literal string `"undefined"` if the subscriber has no linked location.
        received_time:
          type: string
          description: ISO-8601 timestamp with a colon-delimited UTC offset (e.g. `-06:00`), in the subscriber's local timezone.
        mediaUrls:
          type: array
          deprecated: true
          items:
            type: string
          description: Deprecated — use `media_ids` instead. Despite the name this has always contained internal SimpleVoIP attachment IDs, not directly-fetchable URLs; kept for existing integrations. Always an empty array `[]` for plain SMS.
        media_ids:
          type: array
          items:
            type: string
          description: Present for MMS messages; contains internal SimpleVoIP attachment IDs, not directly-fetchable URLs. Always an empty array `[]` for plain SMS. Identical content to the deprecated `mediaUrls` field. Attachment retrieval is not yet part of this public API — reach out to SimpleVoIP support if you need to resolve these IDs.
    SendSmsResponseSuccess:
      type: object
      required:
      - status
      - msg_id
      properties:
        status:
          type: string
          const: success
        msg_id:
          type: string
          format: uuid
    SendSmsRequest:
      type: object
      required:
      - sender
      - recipients
      - body_text
      properties:
        sender:
          type: string
          description: E.164 or short code the message will be sent from. Must be an SMS-enabled number on the authenticated account.
          example: '+15555555555'
        recipients:
          type: array
          minItems: 1
          items:
            type: string
          description: One or more E.164 destination numbers.
          example:
          - '+15555555556'
        body_text:
          type: string
          description: Message body.
        subject:
          type: string
          description: Optional MMS subject line. Omit or send an empty string for plain SMS.
        media:
          type: array
          items:
            type: string
            format: uri
          description: Optional URLs of media to attach as MMS. Omit or send an empty array for plain SMS.
    SendSmsResponseFailure:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: string
          const: failed
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send an `Authorization: Bearer <token>` header. As a fallback for accounts without a bearer token configured, requests from an IP address on the account''s SimpleVoIP-managed allowlist are also accepted — bearer token is the recommended method for new integrations.'
x-refined-from:
- simplevoip.json
- simplevoip-openapi.json