{
  "openapi": "3.0.3",
  "info": {
    "title": "Namirial SMS Gateway API",
    "description": "Send SMS messages worldwide with enterprise-grade reliability and delivery tracking.",
    "version": "27.3.1.6"
  },
  "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.\n\n**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.\n\n**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"
                }
              }
            }
          }
        },
        "summary": "Check service health (admin)",
        "description": "Admin health check endpoint",
        "operationId": "adminCheckServiceStatus",
        "security": []
      }
    },
    "/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.\n\n**Use case**: Send SMS for other accounts without their credentials\n\n**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. The authenticated account does not have Admin privileges.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorInfo"
                },
                "example": {
                  "code": 63,
                  "message": "User user_test not authorized for webmethod send",
                  "details": null
                }
              }
            }
          },
          "500": {
            "description": "Application error. Invalid parameter values may result in HTTP 500.",
            "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
                    }
                  },
                  "INVALID_ACCOUNT": {
                    "value": {
                      "code": 76,
                      "message": "Account nonexistent_account does not exist",
                      "details": null
                    }
                  },
                  "MAX_LENGTH": {
                    "value": {
                      "code": 66,
                      "message": "Message text exceeds maximum length of 1600 characters",
                      "details": null
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        },
        "summary": "Get admin service status",
        "description": "Get detailed admin service status information",
        "operationId": "getAdminStatus",
        "security": []
      }
    },
    "/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.\n\n**Use case**: Monitor service status before sending SMS or in health check routines.\n\n**Request**: POST with empty body (no parameters required)\n\n**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.\n\n**Use case**: Standard SMS sending for your applications (2FA, notifications, alerts).\n\n**Delivery**: Messages are queued and sent asynchronously. Use webhooks or Message Status API to track delivery.\n\n**Character limits**:\n- GSM-7 encoding: 160 chars \n- UCS-2 encoding: 70 chars \n\n",
        "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.\n\n**Format**: `+[country code][number]` (e.g., `+393401234567`)\n\n",
            "pattern": "^\\+[1-9]\\d{6,14}$",
            "example": "+390000000000"
          },
          "text": {
            "type": "string",
            "description": "Message text to send.\n\n**Character limits**:\n- GSM-7: 160 chars (single), 153 chars (multi-part)\n- UCS-2: 70 chars (single), 67 chars (multi-part)\n\n**Encoding**: Automatically detected\n\n**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.\n\n- `true`: Response includes `provider`\n- `false`: Response without `provider`"
          },
          "businessRelationId": {
            "type": "string",
            "maxLength": 255,
            "description": "Business Relation Identifier for One Platform integration.\n\nOverrides default business relation settings."
          },
          "webhook": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ClientWebhookData"
              },
              {
                "description": "Webhook configuration for delivery status notifications.\n\nSee [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": "string",
            "description": "Local Registration Authority identifier"
          }
        },
        "required": [
          "destination",
          "text"
        ]
      },
      "ClientWebhookAuth": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Authentication type",
            "enum": [
              "NONE",
              "JWS"
            ]
          },
          "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.\n\nSee [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.\n\nSee [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,
              76
            ],
            "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": "Invalid message text (empty or exceeds 1600 characters)",
              "74": "Message contains URL but account not configured for URLs",
              "76": "Account does not exist"
            }
          },
          "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., MY_SERVICE). 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.\n\n**Format**: `+[country code][number]` (e.g., `+393401234567`)\n\n",
            "pattern": "^\\+[1-9]\\d{6,14}$",
            "example": "+390000000000"
          },
          "text": {
            "type": "string",
            "description": "Message text to send.\n\n**Character limits**:\n- GSM-7: 160 chars (single), 153 chars (multi-part)\n- UCS-2: 70 chars (single), 67 chars (multi-part)\n\n**Encoding**: Automatically detected\n\n**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.\n\n- `true`: Response includes `provider`\n- `false`: Response without `provider`",
            "default": false
          },
          "businessRelationId": {
            "type": "string",
            "description": "Business Relation Identifier for One Platform integration.\n\nOverrides default business relation settings.",
            "maxLength": 255
          },
          "webhook": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ClientWebhookData"
              },
              {
                "description": "Webhook configuration for delivery status notifications.\n\nSee [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": "Application error. Invalid parameter values may result in HTTP 500.",
        "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
                }
              },
              "MAX_LENGTH": {
                "value": {
                  "code": 66,
                  "message": "Message text exceeds maximum length of 1600 characters",
                  "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.\n\n**Format**: `Authorization: Basic base64(username:password)`\n\n**How to obtain credentials**:\n1. Contact Namirial support to create an SMS account\n2. Receive username and password via secure channel\n3. Test credentials in TEST environment first\n\nSee [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": []
    }
  ]
}