openapi: 3.1.0
info:
  title: BatchSMS API
  description: >+
    # BatchSMS API Description


    The Batch SMS API enables you to efficiently send SMS messages to multiple
    recipients with a single API call. This API offers advanced processing
    features, including batch scheduling, notification callbacks, and detailed
    status tracking.


    ## Key Features


    - **Bulk Processing**: Send up to 1 million SMS messages with a single API
    call

    - **Scheduling**: Schedule batches for future delivery

    - **Status Tracking**: Monitor batch processing status in real-time

    - **Async Notifications**: Receive batch progress notifications via webhooks

    - **Message Templating**: Create personalized messages in a compact format


    ## Base URL


    * https://api.spirius.com/batchsms


    ## HTTP Response Codes used


    * 202 Accepted: Used for successful responses to POST /batches 

    * 200 OK: Used for all other successful responses

    * 400: Malformed request or validation failure

    * 401: Authentication failure

    * 403: Forbidden

    * 404: Not found

    * 409: Conflict

    * 413: Request payload too large

    * 429: Rate limit errors


    ## HTTP Headers


    ### Authorization


    Use Authorization with OAuth2 Bearer token. See Authentication section for
    details on how to obtain the token.

    ```

    Authorization: Bearer <token>

    ```


    ### Content-Type


    Content-Type should be application/json.

    ```

    Content-Type: application/json

    ```


    ### Content-Encoding


    All create batch requests must be compressed with gzip.

    ```

    Content-Encoding: gzip

    ```


    ## Sender ID formats


    The sender_id controls how the sender appears on recipient devices.
    Supported types and rules:


    - **International**
      - Must be in E.164 format (e.g., "+46701234567").

    - **Alphanumeric**
      - Max length: 11 characters.
      - Allowed characters: letters (A–Z, a–z), numbers (0–9), Scandinavian characters (åäöÅÄÖ, æøÆØ), space (not at the beginning or end), dot (.), underscore (_), ampersand (&), and hyphen (-).
      - Note: Scandinavian characters typically only work for Scandinavian recipients.

    - **Shortcode**
      - Digits only.
      - Length: 3–11 characters.

    ## Limitations


    ### Request Size Limits


    * Request size maximum: 32MB

    * SMS length: Maximum 10 concatenated SMS (1600 characters for GSM-7, 700
    for Unicode)


    ### Request Size Examples


    The sizes are estimates derived from test data, there will be variations in
    sizes depending on the actual content and how efficient the content can be
    compressed.


    #### Static message, i.e. same message re-used for all recipients - Max
    length message (10 SMS)


    | Number of GSM-7 characters | Number of recipients/messages | Size -
    Uncompressed | Size - Compressed |

    |----------------------------|-------------------------------|---------------------|-------------------|

    | 1530 (max size)            | 10,000                        | 0.9
    MB              | 0.1 MB            |

    | 1530                       | 100,000                       | 9.1
    MB              | 0.9 MB            |

    | 1530                       | 1,000,000                     | 91
    MB               | 8.4 MB            |


    #### Unique message for each recipient - Small message (1 SMS)


    | Number of GSM-7 characters | Number of recipients/messages | Size -
    Uncompressed | Size - Compressed |

    |----------------------------|-------------------------------|---------------------|-------------------|

    | 160                        | 10,000                        | 2.6
    MB              | 1.3 MB            |

    | 160                        | 100,000                       | 27
    MB               | 13 MB             |

    | 160                        | 1,000,000                     | 266
    MB              | 131 MB            |


    #### Unique message for each recipient - Max length message (10 SMS)


    | Number of GSM-7 characters | Number of recipients/messages | Size -
    Uncompressed | Size - Compressed |

    |----------------------------|-------------------------------|---------------------|-------------------|

    | 1530 (max size)            | 10,000                        | 16
    MB               | 11 MB             |

    | 1530                       | 100,000                       | 157
    MB              | 114 MB            |

    | 1530                       | 1,000,000                     | 1500
    MB             | 1100 MB           |


    > **Note on request size**: 

    > Requests larger than 32MB will be rejected. For large batches with unique
    messages, consider splitting into multiple smaller batches, or using message
    templates with personalization fields.


    > **Note on SMS length**: 

    > A single SMS can contain maximum 160 characters, or maximum 70 characters
    if it contains emojis or any other character 

    > that is not part of the GSM-7 character set. When sending longer messages,
    up to 10 SMS will be automatically concatenated to carry 

    > the message content. The maximum limit is imposed by mobile networks. When
    concatenating SMS, some overhead is used for the concatenation, so the
    actual number of characters in each SMS will be reduced to 153 characters
    for GSM-7 and 67 characters for Unicode. Individual messages that exceeds
    the 10 SMS limit will be rejected and marked as failed in the batch.


    ### Recipients limit - API


    * The API supports batches with up to 1 million recipients, provided that
    the request size does not exceed 32MB.


    ### Recipients limit - SMS Account


    * Each SMS account has a limit on the number of recipients for security and
    performance reasons. Contact your Spirius account manager to activate this
    API and customize the limit to your needs.


    ### Rate Limits


    * Batch requests: 1 r/s (for security reasons)

    * Individual SMS: Up to 100 r/s (configured per account)


    The batch SMS API will dynamically adjust the rate according to the capacity
    of the underlying SMS API 

    and aims to get as close as possible to the max configured rate limit of the
    account.


    ## Data Retention


    * Batch statuses including message details are available up to 7 days after
    processing.

    * This applies to both new requests and scheduled requests (7 days after the
    scheduled start time).


    ## Getting Batch Status updates

    There are two ways to get batch status updates:


    ### Polling


    Use one of the following endpoints to get the status of the batch

    | Endpoint | Description |

    | --- | --- |

    | `/v1/batches/{batch_id}/poll` | Poll batch status, summary only |

    | `/v1/batches/{batch_id}/poll_with_delta` | Poll batch status, summary +
    message delta information |


    ### Event Notifications

    * Configure event callback in `notification_settings` of the create batch
    request. (See details below)


    ## Batch Event Notifications

    To receive asynchronous batch event notifications, set the following fields
    in the batch request:


    * `batch_event_callback_url`: The URL to which the event notifications will
    be sent.

    * `batch_event_callback_token`: An optional token to be included in the
    callback URL.


    ### Callback with Token


    If a token is provided in the request by the client, It is used by the
    server when doing the callbacks. 

    A token can have a max length of 64 characters.


    Token provided in batch request:

    ```json

    {
      ...
      "notification_settings": {
        "batch_event_callback_url": "https://client.com/batchsmsnotifications"
        "batch_event_callback_token": "0fb45e50-86bd-4935-a1e3-6c1ded88d58b",
      }
    }

    ```


    Token used in callback:

    ```

    POST
    https://client.com/batchsmsnotifications?token=0fb45e50-86bd-4935-a1e3-6c1ded88d58b

    ```


    ## Event Types


    ### batch.created


    ```json

    {
      "event_type": "batch.created",
      "timestamp": "2025-03-21T11:15:36Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```


    ### batch.scheduled


    ```json

    {
      "event_type": "batch.scheduled",
      "timestamp": "2025-03-21T11:15:36Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```


    ### batch.processing_started


    ```json

    {
      "event_type": "batch.processing_started",
      "timestamp": "2025-03-21T10:09:59Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```


    ### batch.submission_completed


    ```json

    {
      "event_type": "batch.submission_completed",
      "timestamp": "2025-03-21T10:09:59Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```


    ### batch.submission_progress_update


    ```json

    {
      "event_type": "batch.submission_progress_update",
      "timestamp": "2025-03-21T10:09:59Z",
      "submission_progress_percentage": 95,
      "batch_status_summary": {
        ... // Complete batch status summary information
      },
      "submitted_messages_delta": [
        {
          "id": "c58b5ebb-076d-4058-b3d9-a3a01f230bb2",
          "external_message_id": "1",
          "transaction_id": "02df77cc-b1ce-46b6-89bd-3183a969f855",
          "phone_number": "+34693363516",
          "message": "Hello World!",
          "submission_status": "SUBMITTED",
          "submission_time": "2025-03-21T08:29:00Z",
        },
        {
          "id": "166269f1-6147-4154-afe3-49c8ad616235",
          "external_message_id": "2",
          "transaction_id": "e9f63cfd-1e20-4784-b3a7-d131384f4d32",
          "phone_number": "+34604224206",
          "message": "Hello World!",
          "submission_status": "SUBMITTED",
          "submission_time": "2025-03-21T08:30:00Z",
        }
      ]
    }

    ```


    ### batch.canceled


    ```json

    {
      "event_type": "batch.canceled",
      "timestamp": "2025-03-21T14:47:57Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```


    ### batch.failed


    ```json

    {
      "event_type": "batch.failed",
      "timestamp": "2025-03-21T14:47:57Z",
      "batch_status_summary": {
        ... // Complete batch status summary information
      }
    }

    ```

  contact:
    name: Spirius Support
    url: https://www.spirius.com/contact
    email: support@spirius.com
  version: 1.0.0
  x-api-id: batchsms
  x-api-base-url: https://api.spirius.com/batchsms
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'
        '500':
          description: Internal Server Error - API is experiencing issues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
  /v1/auth/token:
    post:
      tags:
        - Authentication
      summary: OAuth2 Access Token
      description: >-
        OAuth2 token endpoint implementing the client credentials flow.


        This endpoint validates client credentials (SMS API account and key) and

        issues a JWT token if the credentials are valid.


        The client_id is the SMS API account, and the client_secret is the SMS
        API key.


        Args:
            json_data: OAuth2 JSON payload containing client_id and client_secret
            auth_service: AuthService for credential validation and token creation
                      
        Returns:
            Token object containing the JWT access token and metadata
            
        Raises:
            HTTPException: If client authentication fails
      operationId: login_for_access_token_v1_auth_token_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientCredentialsJSON'
        required: true
      responses:
        '200':
          description: OK - Successfully authenticated and received access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: Bad Request - Invalid request format or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid credentials provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: >-
            Internal Server Error - Authentication service temporarily
            unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
  /v1/batches:
    post:
      tags:
        - Batches
      summary: Create a batch
      description: >-
        Create a new batch of SMS messages.


        This endpoint allows you to create a batch of SMS messages to be sent to
        multiple recipients.

        The batch will be processed asynchronously, and you'll receive a batch
        ID to track its status.


        Detailed field descriptions are available in the API schema
        documentation.


        Key capabilities:

        - Personalized messaging via templates, optionally using double curly
        brackets {{field_name}} placeholders combined with 'field_message' for
        value substitution in recipients

        - Support for up to 1,000,000 recipients per batch

        - Scheduled delivery with the `schedule_at` parameter

        - Batch status callbacks and delivery receipt tracking

        - Dry run mode for testing without sending actual messages


        ### Compression Requirement


        This endpoint requires the request to be compressed with gzip due to
        potential

        large payload sizes. Set the 'Content-Encoding: gzip' header and
        compress the request body.
      operationId: create_batch_v1_batches_post
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: content-encoding
          in: header
          required: true
          schema:
            type: string
            description: Must be set to 'gzip' for compressed requests
            title: Content-Encoding
          description: Must be set to 'gzip' for compressed requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateRequest'
      responses:
        '202':
          description: Accepted - Batch has been accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateResponse'
        '400':
          description: Bad Request - Validation error in the batch data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - Account is inactive or lacks required permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '413':
          description: Request Entity Too Large - Request body exceeds size limits
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/batches/{batch_id}:
    get:
      tags:
        - Batches
      summary: Get batch information
      description: |-
        Get comprehensive status and configuration of a batch by its ID.

        This endpoint returns complete batch information including:
        - Batch status summary (status, timestamps, message counts)
        - SMS configuration (sender ID, message template, etc.)
        - Notification settings

        Don't use this endpoint for polling status.
      operationId: get_batch_v1_batches__batch_id__get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
      responses:
        '200':
          description: OK - Returns batch status information including configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchInfoResponse'
        '400':
          description: Bad Request - Invalid batch ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
        '404':
          description: Not Found - Batch with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/batches/{batch_id}/poll:
    get:
      tags:
        - Batches
      summary: Poll batch status summary
      description: >-
        Get batch status summary.


        This endpoint efficiently supports polling for status changes by only
        returning:

        - Current batch status summary


        It's designed for clients to repeatedly call to monitor batch progress.
      operationId: poll_batch_status_v1_batches__batch_id__poll_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
      responses:
        '200':
          description: OK - Returns batch status summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
        '400':
          description: Bad Request - Invalid batch ID or sequence parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not Found - Batch with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/batches/{batch_id}/poll_with_delta:
    get:
      tags:
        - Batches
      summary: Poll batch status summary with messages delta
      description: >-
        Get batch status and message changes since a specific sequence point.


        This endpoint efficiently supports polling for status changes by only
        returning:

        - Current batch status summary

        - Messages that changed status since the last_sequence_id

        - Information about whether more changes are available


        It's designed for clients to repeatedly call to monitor batch progress.
      operationId: poll_batch_status_with_delta_v1_batches__batch_id__poll_with_delta_get
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
        - name: last_sequence_id
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Last Sequence Id
        - name: max_delta_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 2000
            minimum: 1
            default: 500
            title: Max Delta Size
      responses:
        '200':
          description: >-
            OK - Returns batch status and message changes since the specified
            sequence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusDeltaResponse'
        '400':
          description: Bad Request - Invalid batch ID or sequence parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not Found - Batch with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/batches/{batch_id}/cancel:
    post:
      tags:
        - Batches
      summary: Cancel a batch
      description: >-
        Cancel a scheduled batch that has not started processing.


        If the batch is already in processing or completed, a 409 Conflict will
        be returned.
      operationId: cancel_batch_v1_batches__batch_id__cancel_post
      security:
        - OAuth2PasswordBearer: []
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
            title: Batch Id
      responses:
        '200':
          description: OK - Batch successfully canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBatchResponse'
        '400':
          description: Bad Request - Invalid batch ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - Account is inactive or lacks required permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not Found - Batch with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '409':
          description: >-
            Conflict - Batch cannot be canceled because it is already processing
            or completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    APIErrorResponse:
      properties:
        error_code:
          type: string
          title: Error Code
          description: Unique error code identifying the type of error
        error_message:
          type: string
          title: Error Message
          description: Error message
        details:
          anyOf:
            - type: object
            - type: 'null'
          title: Details
          description: Additional error details when available
      type: object
      required:
        - error_code
        - error_message
      title: APIErrorResponse
      description: Standard error response format for the API.
    Batch:
      properties:
        external_batch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Batch Id
          description: External batch identifier
        schedule_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Schedule At
          description: >-
            Scheduled delivery time in ISO 8601 format (e.g.,
            '2023-01-01T12:00:00'). Max 7 days in the future.
        sms_config:
          $ref: '#/components/schemas/BatchSmsConfig-Input'
          description: SMS configuration
        recipients:
          items:
            $ref: '#/components/schemas/BatchRecipient'
          type: array
          title: Recipients
          description: List of recipients to send messages to
        notification_settings:
          anyOf:
            - $ref: '#/components/schemas/BatchNotificationSettings'
            - type: 'null'
          description: Notification settings
      type: object
      required:
        - sms_config
        - recipients
      title: Batch
      description: Structured batch configuration.
    BatchCreateRequest:
      properties:
        batch:
          $ref: '#/components/schemas/Batch'
          description: Batch configuration
      type: object
      required:
        - batch
      title: BatchCreateRequest
      description: Request model for creating a new SMS batch.
    BatchCreateResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique batch ID
      type: object
      required:
        - id
      title: BatchCreateResponse
      description: Response model for batch creation.
    BatchInfoResponse:
      properties:
        batch_status_summary:
          $ref: '#/components/schemas/BatchStatusSummary'
          description: Batch status summary
        sms_config:
          anyOf:
            - $ref: '#/components/schemas/BatchSmsConfig-Output'
            - type: 'null'
          description: SMS configuration
        notification_settings:
          anyOf:
            - $ref: '#/components/schemas/BatchNotificationSettings'
            - type: 'null'
          description: Notification settings
      type: object
      required:
        - batch_status_summary
      title: BatchInfoResponse
    BatchMessageInfo:
      properties:
        id:
          type: string
          title: Id
          description: Unique message ID, created by the Batch SMS API
        external_message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Message Id
          description: Client-defined message ID
        transaction_id:
          type: string
          title: Transaction Id
          description: Unique transaction ID, created by the SMS API
          default: ''
        phone_number:
          type: string
          title: Phone Number
          description: Recipient phone number
        message:
          type: string
          title: Message
          description: The message that was sent
        submission_status:
          $ref: '#/components/schemas/MessageSubmissionStatus'
          description: Current submission status
        submitted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Submitted At
          description: Timestamp when the message was sent
        failed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Failed At
          description: Timestamp when the message failed
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
          description: Error message
      type: object
      required:
        - id
        - phone_number
        - message
        - submission_status
      title: BatchMessageInfo
      description: Response model for a sent message according to API specification.
    BatchNotificationSettings:
      properties:
        batch_event_callback_url:
          title: Batch Event Callback URL
          description: URL where batch status update events will be sent via HTTP POST
        batch_event_callback_token:
          title: Batch Event Callback Token
          description: >-
            Optional token added as a query parameter (e.g. ?token=YOUR_TOKEN)
            for batch callbacks for added security
        batch_event_include_messages_delta:
          title: Include Message Delta in Batch Events
          description: >-
            When true, includes details of individual messages in batch progress
            notifications
        sms_dlr_callback_url:
          title: SMS Delivery Receipt Callback URL
          description: URL where SMS delivery receipts will be sent via HTTP POST
      type: object
      title: BatchNotificationSettings
      description: >-
        Notification settings for receiving updates about batch processing and
        message delivery.
    BatchRecipient:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Phone number of the recipient in E.164 format (e.g., "+46701234567")
        external_message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Message Id
          description: Your identifier for this specific message for tracking purposes
        message_fields:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Message Fields
          description: >-
            Key-value pairs to substitute into the message template (e.g.,
            {"name": "John"})
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: >-
            Custom message text for this recipient only (overrides the batch
            template)
      type: object
      required:
        - phone_number
      title: BatchRecipient
      description: Recipient model for a single message within a batch.
    BatchSmsConfig-Input:
      properties:
        sender_id:
          $ref: '#/components/schemas/SenderId'
          description: >-
            Sender ID configuration specifying how the message appears on
            recipient devices
        message_template:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Template
          description: >-
            Template text with optional placeholders using double curly
            bracketslike {{field_name}} for mass personalization. If
            placeholders are used, use 'message_fields' for value substitution
            in recipients
        type:
          anyOf:
            - $ref: '#/components/schemas/MessageType'
            - type: 'null'
          description: >-
            Message type: 'text' (standard SMS) or 'flash' (appears directly on
            screen without storage)
          default: text
        validity_period:
          anyOf:
            - type: integer
              maximum: 20160
              minimum: 1
            - type: 'null'
          title: Validity Period
          description: >-
            Minutes the message remains valid if undelivered (1-20160, default:
            4320/3 days)
          default: 4320
        client_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Reference
          description: Your reference string for identifying this batch in billing reports
        dry_run:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dry Run
          description: >-
            When true, processes the batch without actually sending messages
            (for testing)
          default: false
      type: object
      required:
        - sender_id
      title: BatchSmsConfig
      description: SMS configuration for a batch of messages.
    BatchSmsConfig-Output:
      properties:
        sender_id:
          $ref: '#/components/schemas/SenderId'
          description: >-
            Sender ID configuration specifying how the message appears on
            recipient devices
        message_template:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Template
          description: >-
            Template text with optional placeholders using double curly
            bracketslike {{field_name}} for mass personalization. If
            placeholders are used, use 'message_fields' for value substitution
            in recipients
        type:
          anyOf:
            - $ref: '#/components/schemas/MessageType'
            - type: 'null'
          description: >-
            Message type: 'text' (standard SMS) or 'flash' (appears directly on
            screen without storage)
          default: text
        validity_period:
          anyOf:
            - type: integer
              maximum: 20160
              minimum: 1
            - type: 'null'
          title: Validity Period
          description: >-
            Minutes the message remains valid if undelivered (1-20160, default:
            4320/3 days)
          default: 4320
        client_reference:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Reference
          description: Your reference string for identifying this batch in billing reports
        dry_run:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dry Run
          description: >-
            When true, processes the batch without actually sending messages
            (for testing)
          default: false
      type: object
      required:
        - sender_id
      title: BatchSmsConfig
      description: SMS configuration for a batch of messages.
    BatchStatus:
      type: string
      enum:
        - CREATED
        - SCHEDULED
        - PROCESSING
        - SUBMISSION_COMPLETED
        - CANCELED
        - FAILED
      title: BatchStatus
    BatchStatusDeltaResponse:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp of when this response was generated
        batch_status_summary:
          $ref: '#/components/schemas/BatchStatusSummary'
          description: Current batch status summary
        next_sequence:
          type: integer
          title: Next Sequence
          description: The sequence number to use for the next poll request
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more changes to retrieve
        submitted_messages_delta:
          items:
            $ref: '#/components/schemas/BatchMessageInfo'
          type: array
          title: Submitted Messages Delta
          description: List of messages that changed status since the last poll
      type: object
      required:
        - batch_status_summary
        - next_sequence
        - has_more
        - submitted_messages_delta
      title: BatchStatusDeltaResponse
      description: >-
        Response model for sequence-based polling of message status changes.


        This model is designed to be similar to the SubmissionProgressEvent
        model

        used for event notifications, but is not an event itself.
    BatchStatusResponse:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp of when this response was generated
        batch_status_summary:
          $ref: '#/components/schemas/BatchStatusSummary'
          description: Current batch status summary
      type: object
      required:
        - batch_status_summary
      title: BatchStatusResponse
      description: >-
        Response model for sequence-based polling of message status changes.


        This model is designed to be similar to the SubmissionProgressEvent
        model

        used for event notifications, but is not an event itself.
    BatchStatusSummary:
      properties:
        id:
          type: string
          title: Id
          description: Unique batch ID
        external_batch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Batch Id
          description: External batch identifier
        account:
          type: string
          title: Account
          description: Account name
        status:
          $ref: '#/components/schemas/BatchStatus'
          description: Current batch status
        total_messages:
          type: integer
          title: Total Messages
          description: Number of messages in the batch
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the batch was created
        scheduled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Scheduled At
          description: Timestamp when the batch is scheduled to start
        processing_started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Processing Started At
          description: Timestamp when the batch started processing
        submission_completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Submission Completed At
          description: Timestamp of when submission was completed
        canceled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Canceled At
          description: Timestamp when the batch was canceled
        failed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Failed At
          description: Timestamp when the batch failed
        messages_submission_status:
          $ref: '#/components/schemas/MessagesSubmissionStatus'
          description: Message submission status counts
      type: object
      required:
        - id
        - account
        - status
        - total_messages
        - created_at
        - messages_submission_status
      title: BatchStatusSummary
      description: Batch status.
    CancelBatchResponse:
      properties:
        batch_status_summary:
          $ref: '#/components/schemas/BatchStatusSummary'
      type: object
      required:
        - batch_status_summary
      title: CancelBatchResponse
    ClientCredentialsJSON:
      properties:
        grant_type:
          type: string
          title: Grant Type
          description: OAuth2 grant type
          default: client_credentials
        client_id:
          type: string
          title: Client Id
          description: SMS API account name
        client_secret:
          type: string
          title: Client Secret
          description: SMS API key
      type: object
      required:
        - client_id
        - client_secret
      title: ClientCredentialsJSON
      description: >-
        OAuth2 JSON payload model for client_credentials grant type.


        This model is used for machine-to-machine authentication in the OAuth2
        client credentials flow

        using JSON payload instead of form data.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
          default: OK
      type: object
      title: HealthResponse
      description: Response model for the health check endpoint
    MessageSubmissionStatus:
      type: string
      enum:
        - PENDING
        - SUBMITTED
        - FAILED
      title: MessageSubmissionStatus
    MessageType:
      type: string
      enum:
        - text
        - flash
      title: MessageType
    MessagesSubmissionStatus:
      properties:
        pending:
          type: integer
          title: Pending
          description: Number of messages received but not yet sent to the SMS API
          default: 0
        submitted:
          type: integer
          title: Submitted
          description: Number of messages successfully sent to the SMS API
          default: 0
        failed:
          type: integer
          title: Failed
          description: Number of messages that failed during submission
          default: 0
      type: object
      title: MessagesSubmissionStatus
      description: Message submission status counts.
    SenderId:
      properties:
        type:
          $ref: '#/components/schemas/SenderIdType'
          description: >-
            Type of sender ID: 'alphanumeric' (letters/numbers), 'international'
            (phone number with country code), or 'shortcode'
        value:
          type: string
          title: Value
          description: |2-

                    The actual sender ID value that will appear on recipient devices
                    
                    For 'alphanumeric', must contain only letters and numbers, Scandinavian characters (åäöÅÄÖ, æøÆØ), space (not at the beginning or end), dot (.), underscore (_), ampersand (&), and hyphen (-), max length 11 characters
                    For 'international', must be in interntational E.164 format, starting with a '+' sign
                    For 'shortcode', must be digits, min length 3, max length 11
                    
      type: object
      required:
        - type
        - value
      title: SenderId
      description: Sender ID configuration for SMS messages.
    SenderIdType:
      type: string
      enum:
        - international
        - alphanumeric
        - shortcode
      title: SenderIdType
    Token:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: bearer
        expires_in:
          type: integer
          title: Expires In
      type: object
      required:
        - access_token
        - expires_in
      title: Token
      description: |-
        OAuth2 token response model.

        Attributes:
            access_token: The JWT access token
            token_type: The token type (always 'bearer')
            expires_in: Token expiration time in seconds
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: token
tags:
  - name: Authentication
    description: Endpoints for obtaining OAuth2 authentication tokens.
  - name: Batches
    description: Endpoints for creating and managing SMS batches.
  - name: Health
    description: API health check endpoints.
servers:
  - url: https://api.spirius.com/batchsms
    description: BatchSMS API server
