> ## Documentation Index > Fetch the complete documentation index at: https://docs.otpiq.com/llms.txt > Use this file to discover all available pages before exploring further. # Send SMS > Send an SMS message. Supports both verification codes and custom messages with multiple provider options. ## OpenAPI ````yaml POST /sms openapi: 3.1.1 info: title: OTPIQ SMS API description: >- Enterprise-grade SMS and messaging API for sending verification codes, custom messages, and managing sender IDs. Supports multiple providers including SMS, WhatsApp, and Telegram with intelligent fallback routing. ## Features * **Multi-Provider Support**: Send messages via SMS, WhatsApp, or Telegram * **Smart Fallback Routes**: Automatic provider switching for maximum delivery success * **Verification Codes**: Automated OTP delivery with customizable codes * **Custom Messages**: Send personalized messages with custom sender IDs * **Rate Limiting**: Built-in protection against abuse * **Spending Controls**: Configurable spending thresholds and credit management * **Real-time Tracking**: Monitor message delivery status * **Sender ID Management**: Register and manage custom sender IDs * **Webhook Notifications**: Real-time delivery status updates via webhooks ## Provider Options OTPIQ now offers 6 provider options including smart fallback routes: - **`whatsapp-sms`**: Try WhatsApp first, fallback to SMS - **`telegram-sms`**: Try Telegram first, fallback to SMS - **`whatsapp-telegram-sms`**: Try WhatsApp → Telegram → SMS (maximum delivery success) - **`sms`**: SMS only - **`whatsapp`**: WhatsApp only - **`telegram`**: Telegram only ## Authentication All API requests require authentication using your project API key. Include it in the Authorization header: ``` Authorization: Bearer sk_live_your_api_key_here ``` ## Webhooks OTPIQ provides real-time delivery status notifications via webhooks. See the Webhooks section for detailed documentation and examples. ## Support * **Documentation**: [https://docs.otpiq.com](https://docs.otpiq.com) * **Support Email**: info@otpiq.com version: 1.0.0 contact: name: OTPIQ Support url: https://otpiq.com email: info@otpiq.com license: name: Commercial url: https://otpiq.com/terms servers: - url: https://api.otpiq.com/api description: Production API security: - bearerAuth: [] tags: - name: Authentication description: API key authentication and project information - name: SMS description: >- Send SMS messages, verification codes, and track delivery with multiple provider options and fallback routing - name: Sender IDs description: Manage custom sender IDs for your messages - name: Webhooks description: Real-time delivery status notifications via webhooks - name: Delivery Reports description: Generate and list CSV delivery reports for SMS/messages in a date range - name: Pricing description: Retrieve international SMS pricing information - name: WhatsApp description: >- List WhatsApp businesses, accounts, phone numbers, and message templates connected to a project externalDocs: description: OTPIQ Documentation url: https://docs.otpiq.com paths: /sms: post: tags: - SMS summary: Send SMS description: >- Send an SMS message. Supports both verification codes and custom messages with multiple provider options. operationId: sendSMS requestBody: description: >- SMS request parameters. First select smsType; inputs show/hide accordingly. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/SmsVerificationRequest' - $ref: '#/components/schemas/SmsCustomMessageRequest' - $ref: '#/components/schemas/SmsWhatsAppTemplateRequest' discriminator: propertyName: smsType mapping: verification: $ref: '#/components/schemas/SmsVerificationRequest' custom: $ref: '#/components/schemas/SmsCustomMessageRequest' whatsapp-template: $ref: '#/components/schemas/SmsWhatsAppTemplateRequest' required: - smsType responses: '200': description: >- SMS sent successfully. Response body includes: message (string), smsId (string), remainingCredit (number), cost (number), canCover (boolean), paymentType ('prepaid' | 'postpaid'). content: application/json: schema: type: object required: - message - smsId - remainingCredit - cost - canCover - paymentType properties: message: type: string description: Success message examples: - SMS task created successfully smsId: type: string description: Unique identifier for the SMS message pattern: ^sms-[a-f0-9]{24}$ examples: - sms-1234567890abcdef123456 remainingCredit: type: number description: Remaining credit balance after the transaction minimum: 0 examples: - 14800 cost: type: number description: Cost of the SMS in IQD minimum: 0 examples: - 200 canCover: type: boolean description: Whether the user has sufficient credit to cover the cost examples: - true paymentType: type: string enum: - prepaid - postpaid description: Payment type of the user account examples: - prepaid examples: success: summary: Successful response value: message: SMS task created successfully smsId: sms-1234567890abcdef123456 remainingCredit: 14800 cost: 200 canCover: true paymentType: prepaid '400': description: Bad request content: application/json: schema: oneOf: - type: object required: - error properties: error: type: string description: Validation error message examples: - >- Phone must be a valid number without any spaces or special characters. - Invalid sms type. - >- When smsType is custom, you must provide (customMessage) - >- Verification code must be between 1 and 20 characters long. - >- When smsType is whatsapp-template, you must provide (templateName) - >- When smsType is whatsapp-template, you must provide (whatsappAccountId) - >- When smsType is whatsapp-template, you must provide (whatsappPhoneId) - Invalid provider. - type: object required: - error - yourCredit - requiredCredit - canCover properties: error: type: string description: Error message examples: - Insufficient credit, please add more credit yourCredit: type: number description: Current credit balance minimum: 0 examples: - 100 requiredCredit: type: number description: Credit required for the transaction minimum: 0 examples: - 200 canCover: type: boolean description: Whether the user can cover the cost examples: - false - type: object required: - error - currentSpending - spendingThreshold - cost properties: error: type: string description: Error message examples: - >- Project spending threshold of 10,000 IQD would be exceeded. Current spending: 9,500 IQD currentSpending: type: number description: Current spending for the project minimum: 0 examples: - 9500 spendingThreshold: type: number description: Spending threshold for the project minimum: 0 examples: - 10000 cost: type: number description: Cost of the transaction minimum: 0 examples: - 200 - type: object required: - error properties: error: type: string description: Error message examples: - SenderID not found - >- SenderID is not accepted, please wait for it to be accepted - type: object required: - error properties: error: type: string description: Error message examples: - >- Account is in trial mode, you can only send sms to your own phone number for verification, add credit to send to other numbers examples: validation: summary: Validation error value: error: >- Phone must be a valid number without any spaces or special characters. insufficient_credit: summary: Insufficient credit value: error: Insufficient credit, please add more credit yourCredit: 100 requiredCredit: 200 canCover: false spending_threshold: summary: Spending threshold exceeded value: error: >- Project spending threshold of 10,000 IQD would be exceeded. Current spending: 9,500 IQD currentSpending: 9500 spendingThreshold: 10000 cost: 200 '401': $ref: '#/components/responses/Unauthorized' '429': description: Rate limit exceeded content: application/json: schema: type: object required: - message - waitMinutes - maxRequests - timeWindowMinutes properties: message: type: string description: Rate limit error message examples: - >- Rate limit exceeded. Please try again in 8 minutes. Maximum 10 requests allowed per phone number in 10 minutes. waitMinutes: type: number description: Minutes to wait before retrying minimum: 0 examples: - 8 maxRequests: type: number description: Maximum requests allowed minimum: 1 examples: - 10 timeWindowMinutes: type: number description: Time window in minutes minimum: 1 examples: - 10 examples: rate_limit: summary: Rate limit exceeded value: message: >- Rate limit exceeded. Please try again in 8 minutes. Maximum 10 requests allowed per phone number in 10 minutes. waitMinutes: 8 maxRequests: 10 timeWindowMinutes: 10 '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: SmsVerificationRequest: title: Verification Message type: object required: - phoneNumber - smsType - verificationCode properties: phoneNumber: type: string description: Phone number in international format without + (e.g., 964750123456) pattern: ^[0-9]{10,15}$ examples: - '964750123456' smsType: type: string description: >- Must be set to "verification" for sending verification codes. This value determines the message type and required fields. verificationCode: type: string description: Verification code to send minLength: 1 maxLength: 20 examples: - '123456' senderId: type: string description: Optional sender ID to use for the message maxLength: 11 examples: - OTPIQ whatsappAccountId: type: string description: >- Optional WhatsApp Business Account ID for using custom WhatsApp sender examples: - 68c46fecc509cdcec8fb3ef2 whatsappPhoneId: type: string description: Optional WhatsApp Phone Number ID for using custom WhatsApp sender examples: - 68da31fb518ac3db3eb0a0f4 templateName: type: string description: Optional WhatsApp template name for using custom WhatsApp sender examples: - verification_template provider: type: string enum: - auto - whatsapp-sms - telegram-sms - whatsapp-telegram-sms - sms - whatsapp - telegram description: Provider/channel to use default: auto examples: - whatsapp-sms deliveryReport: description: Optional webhook delivery report configuration type: object properties: webhookUrl: type: string format: uri description: The HTTPS URL where delivery status updates will be sent examples: - https://your-app.com/webhooks/sms-status deliveryReportType: type: string enum: - all - final description: Controls when webhooks are triggered default: all webhookSecret: type: string description: Optional secret key for webhook authentication minLength: 1 maxLength: 200 pattern: ^[\w!#$%&'*+\-.^_`|~]+$ examples: - your_webhook_secret_123 SmsCustomMessageRequest: title: Custom Message type: object required: - phoneNumber - smsType - customMessage properties: phoneNumber: type: string description: Phone number in international format without + (e.g., 964750123456) pattern: ^[0-9]{10,15}$ examples: - '964750123456' smsType: type: string description: >- Must be set to "custom" for sending custom messages with your own content. This value determines the message type and required fields. customMessage: type: string description: Custom message to send maxLength: 1000 examples: - 'Your order #12345 has been confirmed. Thank you for your purchase!' senderId: type: string description: Optional sender ID to use for the message maxLength: 11 examples: - OTPIQ whatsappAccountId: type: string description: >- Optional WhatsApp Business Account ID for using custom WhatsApp sender examples: - 68c46fecc509cdcec8fb3ef2 whatsappPhoneId: type: string description: Optional WhatsApp Phone Number ID for using custom WhatsApp sender examples: - 68da31fb518ac3db3eb0a0f4 templateName: type: string description: Optional WhatsApp template name for using custom WhatsApp sender examples: - custom_template provider: type: string enum: - auto - whatsapp-sms - telegram-sms - whatsapp-telegram-sms - sms - whatsapp - telegram description: Provider/channel to use default: auto examples: - sms deliveryReport: description: Optional webhook delivery report configuration type: object properties: webhookUrl: type: string format: uri description: The HTTPS URL where delivery status updates will be sent examples: - https://your-app.com/webhooks/sms-status deliveryReportType: type: string enum: - all - final description: Controls when webhooks are triggered default: all webhookSecret: type: string description: Optional secret key for webhook authentication minLength: 1 maxLength: 200 pattern: ^[\w!#$%&'*+\-.^_`|~]+$ examples: - your_webhook_secret_123 SmsWhatsAppTemplateRequest: title: WhatsApp Template Message type: object required: - phoneNumber - smsType - templateName - whatsappAccountId - whatsappPhoneId properties: phoneNumber: type: string description: Phone number in international format without + (e.g., 964750123456) pattern: ^[0-9]{10,15}$ examples: - '964750123456' smsType: type: string description: >- Must be set to "whatsapp-template" for sending WhatsApp template messages. This value determines the message type and required fields. templateName: type: string description: WhatsApp template name examples: - template_name whatsappAccountId: type: string description: WhatsApp Business Account ID examples: - 68c46fecc509cdcec8fb3ef2 whatsappPhoneId: type: string description: WhatsApp Phone Number ID examples: - 68da31fb518ac3db3eb0a0f4 senderId: type: string description: Optional sender ID to use for the message maxLength: 11 examples: - OTPIQ provider: type: string enum: - auto - whatsapp-sms - telegram-sms - whatsapp-telegram-sms - sms - whatsapp - telegram description: Provider/channel to use default: auto examples: - whatsapp deliveryReport: description: Optional webhook delivery report configuration type: object properties: webhookUrl: type: string format: uri description: The HTTPS URL where delivery status updates will be sent examples: - https://your-app.com/webhooks/sms-status deliveryReportType: type: string enum: - all - final description: Controls when webhooks are triggered default: all webhookSecret: type: string description: Optional secret key for webhook authentication minLength: 1 maxLength: 200 pattern: ^[\w!#$%&'*+\-.^_`|~]+$ examples: - your_webhook_secret_123 responses: Unauthorized: description: Unauthorized content: application/json: schema: type: object required: - message properties: message: type: string description: Unauthorized error message examples: - Unauthorized, please use your project api key InternalServerError: description: Internal Server Error content: application/json: schema: type: object required: - message properties: message: type: string description: Internal server error message examples: - Internal server error securitySchemes: bearerAuth: type: http scheme: bearer description: >- Project API key (`sk_live…` or `sk_dev…`). Send it as `Authorization: Bearer `. ````