openapi: 3.1.0
info:
  title: ReplyPath API
  description: >
    # Replypath API Description


    The Replypath API enables you to send SMS messages and track individual
    responses. It provides a unique ReplyPath number for each outgoing message,
    allowing recipients to reply directly. These replies are then correlated
    with the original message and can be delivered to your system via callbacks.


    ## Core Concepts


    *   **ReplyPath Number**: A unique phone number allocated from a pool, used
    as the sender ID for an outgoing SMS. Replies to this number are routed back
    to your application.

    *   **One-Shot Messages**: A ReplyPath number can be configured as
    "one-shot," meaning it's released (and the original message record deleted)
    after the first reply is received. This is useful for transactional messages
    where only a single response is expected.

    *   **Callbacks**: Your system can receive incoming MO (Mobile Originated)
    SMS messages by configuring a replypath callback URL. The API will send the
    message details to this URL either via GET or POST request, depending on the
    configured protocol.

    *   **DLR (Delivery Receipt)**: A delivery receipt is sent to the callback
    URL configured for the account when the SMS has been successfully delivered
    to the recipient's phone.

    *   **Validity Period (VP)**: Determines how long an allocated ReplyPath
    number remains active and how long the network will attempt to deliver the
    SMS. Replies can only be received during this period.


    ## Key Features


    *   Send individual SMS messages.

    *   Receive replies to sent messages via unique ReplyPath numbers.

    *   Webhook/callback integration for incoming MO SMS.

    *   Configurable validity period for ReplyPath numbers.

    *   "One-shot" message support for single-reply scenarios.

    *   Automatic management of a pool of ReplyPath numbers.

    *   Basic Authentication for secure API access.


    ## Basic Workflow


    1.  **Send SMS**: Your application makes a POST request to the
    `replypath/v1/sendsms` endpoint with the message details, recipient(s), and
    desired validity period.

    2.  **ReplyPath Allocation**: The API allocates a unique ReplyPath number
    from its pool for the specified validity period.

    3.  **SMS Delivery**: The SMS is sent to the recipient(s) with the ReplyPath
    number as the sender ID.

    4.  **Delivery Report**: If DLR is requested, and a DLR callback is
    configured for the account, the Spirius message server sends a delivery
    report to the configured callback URL.

    5.  **Recipient Replies**: The recipient replies to the SMS. The reply is
    sent to the ReplyPath number.

    6.  **MO SMS Processing**: The API receives the MO SMS.
        *   It identifies the original MT (Mobile Terminated) message and associated account based on the ReplyPath number.
        *   The MO SMS is stored.
    7.  **Callback Delivery**: If a callback URL is configured for the account,
    the API sends the MO SMS details to your URL via a GET or POST request,
    depending on the configured protocol.

    8.  **One-Shot Cleanup**: If the original message was "one-shot," the
    ReplyPath number is released, and the original sent message record is
    deleted after the first reply is processed.


    ### Use Case Example


    1. You send the question What time are you coming? to mobile user
    +46123456789.

    2. You get transaction-id {1} in return from the Smart Replypath API.

    3. You send another question What time does the game start? to the same
    mobile user.

    4. You get transaction-id {2} in return from the Smart Replypath API.

    5. The mobile user replies to one of the questions with the text At 10:30.

    6. You get the message At 10:30 received in response to {1} from the Smart
    Replypath application.


    This functionality is achieved by using a unique phone number as sender for
    each question. When the user responds to a question, the reply can be mapped
    to the question using the unique phone number.


    The mapping for the unique numbers will be kept for a limited time only,
    this time is called the Validity Period (VP). The default VP value is three
    days. Any response coming in after the VP has expired will not be forwarded.


    Because Smart Replypath require functionality provided by Extended Virtual
    Numbers, it will only work within Sweden which is the only country where the
    mobile phone networks are configured to allow extension digits to be added
    to a mobile phone number.


    ## HTTP Response Codes used


    *   `200 OK`: Used for successful GET requests and synchronous operations.

    *   `400 Bad Request`: Malformed request syntax, invalid request message
    framing, or deceptive request routing. Also used for validation failures
    (e.g., invalid parameters, missing required fields).

    *   `401 Unauthorized`: Authentication failure. Client lacks valid
    credentials.

    *   `403 Forbidden`: Authenticated client does not have permission to access
    the requested resource.

    *   `429 Too Many Requests`: Rate limit exceeded.

    *   `500 Internal Server Error`: A generic error message, given when an
    unexpected condition was encountered and no more specific message is
    suitable.

    *   `503 Service Unavailable`: The server is currently unable to handle the
    request due to a temporary overload or maintenance of the server.


    ## HTTP Headers


    ### Authorization


    Basic auth with SMS account username and password.

    ```

    Authorization: Basic <base64_encoded_username:password>

    ```


    ### Content-Type


    Content-Type should be application/json.

    ```

    Content-Type: application/json

    ```


    ## Limitations


    ### SMS Message Length

    * A single SMS can contain a maximum of 160 characters if it only uses
    characters from the GSM-7 character set. If it contains any characters not
    in GSM-7 (e.g., emojis, accented characters), it's treated as Unicode
    (UCS-2), and the limit becomes 70 characters per SMS part.

    * When sending longer messages, the message is split into multiple parts
    (concatenated SMS). Up to 10 SMS parts can be concatenated.

    * Due to concatenation headers, the character limit per part is reduced to
    153 for GSM-7 and 67 for Unicode.

    * Messages exceeding the total limit (e.g., >10 parts) will be rejected.

    * Messages must be between 1 and 1530 characters in length.


    ### Rate Limits

    * Configured per account, up to a maximum of 100 r/s. Check your account
    details.

    * Exceeding the rate limit will result in `429 Too Many Requests` errors.


    ### Character Encoding

    * The API expects request bodies (JSON) to be UTF-8 encoded.

    * SMS message content (`Msg` field) will be processed to automatically
    determine if it's GSM-7 or Unicode for sending.


    ### Phone Number Format


    The API will normalize the phone number to a standard format, removing any
    non-digit characters and ensuring a consistent format, however the
    recommended format is international with a leading `+` (E.164)

    * Accepted international formats should have a leading `+` or `00`, e.g.
    `+46123456789` or `0046123456789`

    * Accepted national formats starts with `0`, e.g. `0701234567`. If national
    format is used, the API assumes that the number is Swedish


    ## Data Retention


    * **Sent Messages (MT)**: Stored for the duration of their `validity_period`
    (VP) or until a reply is received if `one_shot` is true. The VP determines
    how long the ReplyPath number is active.

    * **Received Messages (MO)**: Stored and linked to the original MT message.
    They expire when the original MT message's `validity_period` ends.

    * **Default Validity Period**: The default VP is 3 days if not specified by
    the client. This is also the maximum configurable period. Clients can
    specify shorter VPs.

    * **OneShot Behavior**: If `one_shot` is true for a sent message:
        * The ReplyPath number reservation and the sent message record are deleted from the system after the *first* MO reply associated with that MT message is successfully processed (including callback attempt).
        * Subsequent replies to that (now-deleted) ReplyPath number reservation will not be processed or linked.

    ## Callback Protocol


    * The API will send the MO SMS details to the callback URL configured for
    the account.

    * The callback URL should be a valid HTTP or HTTPS URL.

    * The API will send the MO SMS details to the callback URL via a GET or POST
    request, depending on the configured protocol.

    * The callback URL should be able to handle the MO SMS details in JSON
    format.


    ## Resend functionality

    If the delivery of the reply message to the callback URL fails, the API will
    attempt to resend the message to the callback URL. The resend attempts will
    continue regularly until the message is successfully delivered or the
    message record is deleted (after Validity Period has expired).


    ### HTTP GET Example


    ```

    127.0.0.1 - - [15/Sep/2016 20:31:45] "GET
    /reply?Msg=Ja+tack&InResponseTo=2531e755-71d0-4449-bb0c-e5657d13c570

    ```


    ### HTTP POST Example


    ```

    127.0.0.1 - - [15/Sep/2025 20:59:10] "POST /reply HTTP/1.1" 200 -

    {
        "From": "+46123456789",
        "InResponseTo": "21d318ca-6598-4e3a-9212-f6b8ab5e79ae",
        "Msg": "Ja tack"
    }

    ```


    ## Error Handling


    * The API uses standard HTTP status codes to indicate success or failure.

    * Error responses are in JSON format and include a code and an error message
    and optionally a details object.

    * Example:
        ```json
        {
            "code": "VALIDATION_ERROR",
            "message": "Field required",
            "details": {
                "loc": ["body", "To"],
                "msg": "Field required",
                "type": "missing"
            }
        }
        ```
  contact:
    name: Spirius Support
    url: https://www.spirius.com/contact
    email: support@spirius.com
  version: 1.0.0
  x-api-id: replypath
  x-api-base-url: https://api.spirius.com/replypath
paths:
  /health:
    get:
      tags:
        - Health
      summary: API Health Check
      description: >-
        Simple health check endpoint that verifies the API is operational.


        Returns a JSON response with "status": "OK" when the API is functioning
        correctly.

        This endpoint can be used by monitoring systems to verify API
        availability.


        Returns:
            HealthResponse: Status information indicating the API is healthy
      operationId: health_check_health_get
      responses:
        '200':
          description: OK - API is healthy and operational
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /v1/sendsms:
    post:
      tags:
        - Sendsms
      summary: Send SMS Message
      description: Send an SMS message using the ReplyPath API
      operationId: send_sms_v1_sendsms_post
      security:
        - HTTPBasic: []
      parameters:
        - name: instantiate
          in: query
          required: false
          schema:
            type: boolean
            default: true
            title: Instantiate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsRequest'
      responses:
        '200':
          description: SMS message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSmsResponse'
        '400':
          description: >-
            Validation Error - Invalid SMS request parameters (e.g., invalid
            number, message too long)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - Insufficient permissions or account issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error - Request body does not conform to schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
components:
  schemas:
    APIErrorResponse:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
      type: object
      required:
        - code
        - message
      title: APIErrorResponse
      description: Standard error response model for API errors.
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
          default: OK
      type: object
      title: HealthResponse
      description: Response model for the health check endpoint
    SendSmsRequest:
      properties:
        To:
          type: string
          maxLength: 17
          minLength: 10
          title: To
          description: Phone number(s) of the recipient(s), comma or semicolon separated
        Msg:
          type: string
          maxLength: 1530
          minLength: 1
          title: Msg
          description: SMS message content
        DLR:
          type: integer
          maximum: 1
          minimum: 0
          title: Dlr
          description: >-
            Delivery report flag (0 = no delivery report, 1 = delivery report
            requested)
          default: 0
        VP:
          type: integer
          maximum: 4320
          minimum: 0
          title: Vp
          description: 'Validity period in minutes (default: 3 days)'
          default: 4320
        OneShot:
          type: integer
          maximum: 1
          minimum: 0
          title: Oneshot
          description: OneShot flag (0 = normal SMS, 1 = OneShot SMS)
          default: 0
      type: object
      required:
        - To
        - Msg
      title: SendSmsRequest
      description: >-
        SMS Request Schema - Matches legacy API


        Defines the structure for sending SMS messages exactly matching the
        legacy API
      example:
        DLR: 0
        Msg: Your verification code is 123456
        OneShot: 0
        To: '+46701234567'
        VP: 4320
    SendSmsResponse:
      properties:
        TransactionId:
          type: string
          title: Transactionid
          description: Transaction ID for tracking the sent message
        DestinationAddress:
          type: string
          title: Destinationaddress
          description: Recipient phone number
        OriginatorAddress:
          type: string
          title: Originatoraddress
          description: The allocated reply path number (originator of the MT SMS)
      type: object
      required:
        - TransactionId
        - DestinationAddress
        - OriginatorAddress
      title: SendSmsResponse
      description: |-
        SMS Response

        Defines the structure for a single SMS send response
      example:
        DestinationAddress: '+467312937461276'
        OriginatorAddress: '+46739876543'
        TransactionId: 826004b6-e2dd-443f-ac92-39452fd30f66
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
tags:
  - name: Health
    description: API health check endpoints.
servers:
  - url: https://api.spirius.com/replypath
    description: ReplyPath API server
