openapi: 3.0.3
info:
  title: Namirial SMS Gateway API
  description: >-
    Send SMS messages worldwide with enterprise-grade reliability and delivery
    tracking.
  version: 27.1.0.4
servers:
  - url: https://sms.namirialtsp.com
    description: Production environment
  - url: https://sms.preprod.namirialtsp.com
    description: Pre-production staging environment (coming soon)
  - url: https://sms.test.namirialtsp.com
    description: Development and testing environment
tags:
  - name: SmsServices
    description: |-
      Send SMS messages using your account credentials.

      **Authentication**: HTTP Basic Auth required
    externalDocs:
      description: SMS Services Documentation
      url: >-
        https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/api-references/services-send
  - name: SmsAdmin
    description: |-
      Send SMS with administrative privileges on behalf of other accounts.

      **Authentication**: HTTP Basic Auth required
    externalDocs:
      description: Admin API Documentation
      url: >-
        https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/api-references/admin-send
paths:
  /api/Admin/checkServiceStatus:
    post:
      tags:
        - SmsAdmin
      responses:
        '200':
          description: Service is operational.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                globalStatus: true
                dbStatus: true
                servicesStatus: true
                errorMessage: ''
                versionNumber: 27.1.0.2
        '403':
          description: >-
            Access denied. This endpoint requires Admin account privileges. The
            response body is an HTML page.
      summary: Check service health (admin)
      description: Admin health check endpoint
      operationId: adminCheckServiceStatus
  /api/Admin/send:
    post:
      tags:
        - SmsAdmin
      summary: Send SMS with admin privileges
      description: >-
        Send an SMS message on behalf of another account using admin
        credentials.


        **Use case**: Send SMS for other accounts without their credentials


        **Additional parameters**: `account` and `lra` (Local Registration
        Authority)
      operationId: adminSendSms
      requestBody:
        description: Send parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminSendRequestBody'
            example:
              destination: '+390000000000'
              text: 'Your verification code is: 123456'
              account: account-username
              lra: 123456
              reference:
                service: DIGITALSIGN
                action: AUTH
                key: dfg6hwrt356hd
              businessRelationId: '123456789'
              webhook:
                url: https://example.com/webhook
              detailed: true
      responses:
        '200':
          $ref: '#/components/responses/SendSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Access denied. This endpoint requires Admin account privileges. The
            response body is an HTML page.
        '500':
          $ref: '#/components/responses/Error'
  /api/Admin/status:
    get:
      tags:
        - SmsAdmin
      responses:
        '200':
          description: Service is operational.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                globalStatus: true
                dbStatus: true
                servicesStatus: true
                errorMessage: ''
                versionNumber: 27.1.0.2
        '403':
          description: >-
            Access denied. This endpoint requires Admin account privileges. The
            response body is an HTML page.
      summary: Get admin service status
      description: Get detailed admin service status information
      operationId: getAdminStatus
  /api/Services/checkServiceStatus:
    post:
      tags:
        - SmsServices
      responses:
        '200':
          description: Service is operational.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                globalStatus: true
                dbStatus: true
                servicesStatus: true
                errorMessage: ''
                versionNumber: 27.1.0.2
      summary: Check service health
      description: >-
        Health check endpoint to verify SMS Gateway availability.


        **Use case**: Monitor service status before sending SMS or in health
        check routines.


        **Request**: POST with empty body (no parameters required)


        **Response**: HTTP 200 if service is operational
      operationId: checkServiceStatus
      security: []
  /api/Services/send:
    post:
      tags:
        - SmsServices
      summary: Send SMS message
      description: >+
        Send an SMS message to a destination phone number using your account
        credentials.


        **Use case**: Standard SMS sending for your applications (2FA,
        notifications, alerts).


        **Delivery**: Messages are queued and sent asynchronously. Use webhooks
        or Message Status API to track delivery.


        **Character limits**:

        - GSM-7 encoding: 160 chars 

        - UCS-2 encoding: 70 chars 

      operationId: sendSms
      requestBody:
        description: Send parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicesSendRequestBody'
            example:
              destination: '+390000000000'
              text: 'Your verification code is: 123456'
              reference:
                service: SPID
                action: VERIFICATION
                key: '123123456456'
              businessRelationId: '123456789'
              webhook:
                url: https://example.com/webhook
              detailed: false
      responses:
        '200':
          $ref: '#/components/responses/SendSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/Error'
  /api/Services/status:
    get:
      tags:
        - SmsServices
      responses:
        '200':
          description: Service is operational.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatusResponse'
              example:
                globalStatus: true
                dbStatus: true
                servicesStatus: true
                errorMessage: ''
                versionNumber: 27.1.0.2
      summary: Get service status
      description: Get detailed service status information
      operationId: getServicesStatus
      security: []
components:
  schemas:
    AdminSendRequestBody:
      type: object
      properties:
        destination:
          type: string
          description: |+
            Destination phone number in E.164 international format.

            **Format**: `+[country code][number]` (e.g., `+393401234567`)

          pattern: ^\+[1-9]\d{6,14}$
          example: '+390000000000'
        text:
          type: string
          description: |-
            Message text to send.

            **Character limits**:
            - GSM-7: 160 chars (single), 153 chars (multi-part)
            - UCS-2: 70 chars (single), 67 chars (multi-part)

            **Encoding**: Automatically detected

            **Special characters**: Emojis trigger UCS-2 (higher cost)
          minLength: 1
          maxLength: 1600
        reference:
          $ref: '#/components/schemas/ReferenceService'
        attemptCount:
          format: int32
          type: integer
          deprecated: true
          description: >-
            **DEPRECATED**: No longer used. Retry logic is handled
            automatically.
        detailed:
          type: boolean
          default: false
          description: |-
            Return detailed response including provider name.

            - `true`: Response includes `provider`
            - `false`: Response without `provider`
        businessRelationId:
          type: string
          maxLength: 255
          description: |-
            Business Relation Identifier for One Platform integration.

            Overrides default business relation settings.
        webhook:
          allOf:
            - $ref: '#/components/schemas/ClientWebhookData'
            - description: >-
                Webhook configuration for delivery status notifications.


                See [Webhook
                Configuration](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/wb/wb-configuration)
                for details.
        account:
          type: string
          description: Target account username to send SMS on behalf of
        lra:
          type: integer
          description: Local Registration Authority identifier
          format: int32
      required:
        - destination
        - text
    ClientWebhookAuth:
      type: object
      properties:
        type:
          type: string
          description: Authentication type
          enum:
            - NONE
        value:
          type: string
          description: ''
      description: Authentication for webhook requests
    ClientWebhookData:
      type: object
      properties:
        url:
          type: string
          description: Webhook endpoint URL (must be HTTPS)
          format: uri
        authentication:
          $ref: '#/components/schemas/ClientWebhookAuth'
      description: >-
        Webhook configuration for delivery status notifications.


        See [Webhook
        Configuration](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/wb/wb-configuration)
        for details.
    ErrorInfo:
      type: object
      properties:
        code:
          format: int32
          type: integer
          description: >-
            Machine-readable error code.


            See [Error
            Codes](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/integration-guide/error-codes)
            for complete list.
          enum:
            - 8
            - 56
            - 59
            - 60
            - 61
            - 63
            - 64
            - 66
            - 74
          x-enum-descriptions:
            '8': Wrong destination number format
            '56': Invalid or unreachable number
            '59': Invalid reference service identifier
            '60': Message blocked by anti-flooding protection
            '61': Destination number in watchlist (permanently blocked)
            '63': Authentication error (missing or invalid credentials)
            '64': SMS provider temporarily unavailable
            '66': Empty or missing message text
            '74': Message contains URL but account not configured for URLs
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: string
          description: Additional error details or troubleshooting hints
          nullable: true
      required:
        - code
        - message
    ReferenceService:
      type: object
      properties:
        service:
          type: string
          description: >-
            Service identifier (e.g., AUTHENTICATION, ECOMMERCE, DIGITALSIGN).
            Required if `action` or `key` are specified. Must match one of the
            predefined allowed values — see [Reference
            Attribute](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/integration-guide/attribute-reference).
          maxLength: 50
        action:
          type: string
          description: Action within the service (e.g., 2FA, PASSWORD_RESET)
          maxLength: 50
        key:
          type: string
          description: Custom tracking key (e.g., user ID, order ID)
          maxLength: 255
      description: >-
        Tracking reference to correlate SMS with your business logic. If any
        field is specified, `service` is required.
    SendResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique message identifier (UUID). Use to query status via Message
            Status API.
        message:
          type: string
          description: 'Status message. Format: `<code>: <description>`. Code 0 = accepted.'
        provider:
          type: string
          description: SMS provider used (only when detailed=true).
          nullable: true
      required:
        - id
        - message
    ServicesSendRequestBody:
      type: object
      properties:
        destination:
          type: string
          description: |+
            Destination phone number in E.164 international format.

            **Format**: `+[country code][number]` (e.g., `+393401234567`)

          pattern: ^\+[1-9]\d{6,14}$
          example: '+390000000000'
        text:
          type: string
          description: |-
            Message text to send.

            **Character limits**:
            - GSM-7: 160 chars (single), 153 chars (multi-part)
            - UCS-2: 70 chars (single), 67 chars (multi-part)

            **Encoding**: Automatically detected

            **Special characters**: Emojis trigger UCS-2 (higher cost)
          minLength: 1
          maxLength: 1600
        reference:
          $ref: '#/components/schemas/ReferenceService'
        attemptCount:
          format: int32
          type: integer
          deprecated: true
          description: >-
            **DEPRECATED**: No longer used. Retry logic is handled
            automatically.
        detailed:
          type: boolean
          description: |-
            Return detailed response including provider name.

            - `true`: Response includes `provider`
            - `false`: Response without `provider`
          default: false
        businessRelationId:
          type: string
          description: |-
            Business Relation Identifier for One Platform integration.

            Overrides default business relation settings.
          maxLength: 255
        webhook:
          allOf:
            - $ref: '#/components/schemas/ClientWebhookData'
            - description: >-
                Webhook configuration for delivery status notifications.


                See [Webhook
                Configuration](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/wb/wb-configuration)
                for details.
      required:
        - destination
        - text
    ServiceStatusResponse:
      type: object
      required:
        - globalStatus
        - dbStatus
        - servicesStatus
        - versionNumber
      properties:
        globalStatus:
          type: boolean
          description: Overall service availability.
        dbStatus:
          type: boolean
          description: Database connectivity status.
        servicesStatus:
          type: boolean
          description: Internal services availability.
        errorMessage:
          type: string
          description: >-
            Error message if any component is unavailable. Empty string when all
            systems are operational.
        versionNumber:
          type: string
          description: Current API version.
          example: 27.1.0.2
  responses:
    Error:
      description: SMS delivery error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            WRONG_NUMBER:
              value:
                code: 8
                message: Wrong number error
            EMPTY_TEXT:
              value:
                code: 66
                message: Empty or missing message text
                details: null
    Unauthorized:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            MISSING:
              value:
                code: 63
                message: Missing basic authentication header
            NOT_VALID:
              value:
                code: 63
                message: Username or password not valid
    SendSuccess:
      description: SMS accepted for delivery.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendResponse'
          examples:
            accepted:
              summary: SMS accepted (detailed=false)
              value:
                id: 7b8ef313-f1f2-4c4f-bffa-438c287ba9d8
                message: '0: Accepted for delivery'
            accepted-detailed:
              summary: SMS accepted (detailed=true)
              value:
                id: be67210b-072a-40b2-9278-014caeba6bc9
                message: '0: Accepted for delivery'
                provider: PROVIDER1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using account credentials.


        **Format**: `Authorization: Basic base64(username:password)`


        **How to obtain credentials**:

        1. Contact Namirial support to create an SMS account

        2. Receive username and password via secure channel

        3. Test credentials in TEST environment first


        See [Authentication
        documentation](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/authentication)
        for details.
externalDocs:
  description: Complete SMS Gateway Documentation
  url: https://docs.namirial.app/products/sms/homepage
security:
  - basicAuth: []
