IconicSMS API for sending SMS.
\nSend an OTP:
\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\nSend an OTP with your own text ([[code]] is replaced by the generated code):
https://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\nSend an SMS:
\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\nSend an SMS from a specific sender:
\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\nCheck your balance:
\nhttps://api.iconicsms.et/api/v1/balance?token=\nReplace 2519XXXXXXXX with the receiver and with your API key. Every endpoint also accepts POST (form data or JSON).
Create an API key in the dashboard under Developer → API Keys; you can view it again there at any time. Send it as the token parameter, the X-IconicSMS-Key header, X-API-Key or Authorization: Bearer <key>. Prefer a header in server code so the key does not appear in URLs and logs.
shortcode_id (sender_id for bulk) is optional. Without it the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.
Every response uses { success, data, meta, error }. A 202 send response means the SMS is queued, not yet delivered. Live keys send real SMS billed from your wallet; test keys simulate sending.
Example (GET)
\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\nReplace 2519XXXXXXXX with the receiver and with your API key. The second example uses your own text; [[code]] is replaced by the generated code.
Generates a random 6-digit code, sends it to phone and returns 202 with data.code and data.message. Store the code (hashed, with an expiry) in your application and verify it there.
Your IconicSMS API key (starts with iconicsms_live_sk_ or iconicsms_test_sk_). Create one in the dashboard under API Keys. Test keys use the mock provider and are never delivered.
(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.
\n","type":"text/plain"},"key":"shortcode_id","value":"your shortcode_id"},{"description":{"content":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.
\n","type":"text/plain"},"key":"phone","value":"your phone number"},{"disabled":true,"description":{"content":"(optional) Your own OTP text. Put [[code]] where the code should appear, e.g. Your Tina verification code is [[code]] or Your reset verification code is [[code]]. If [[code]] is missing, the code is added at the end. If not specified: Your verification code is <code>. The code is always generated by IconicSMS (6 digits).
`. The code is always generated by IconicSMS (6 digits).","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"message\": {\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"to\": \"+251911234567\",\n \"from\": \"ICONIC\",\n \"body\": \"Your Tina verification code is 482913\",\n \"status\": \"queued\",\n \"message_type\": \"otp\",\n \"segment_count\": 1,\n \"estimated_cost\": \"0.350000\",\n \"created_at\": \"2026-10-05T10:00:00+03:00\"\n },\n \"code\": \"482913\"\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"adc40e80-cda2-4040-9a95-e35eae08dcb5","name":"401 Invalid API key","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/otp?token=&phone=your phone number","host":["https://api.iconicsms.et"],"path":["api","v1","sms","otp"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put `[[code]]` where the code should appear, e.g. `Your Tina verification code is [[code]]` or `Your reset verification code is [[code]]`. If `[[code]]` is missing, the code is added at the end. If not specified: `Your verification code is `. The code is always generated by IconicSMS (6 digits).","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"7d5de2ec-2641-45ea-b5e2-4d0934497078","name":"402 Insufficient balance","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/otp?token=&phone=your phone number","host":["https://api.iconicsms.et"],"path":["api","v1","sms","otp"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put `[[code]]` where the code should appear, e.g. `Your Tina verification code is [[code]]` or `Your reset verification code is [[code]]`. If `[[code]]` is missing, the code is added at the end. If not specified: `Your verification code is `. The code is always generated by IconicSMS (6 digits).","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"insufficient_balance\",\n \"message\": \"Insufficient wallet balance to send this message.\",\n \"details\": {\n \"required_amount\": \"0.350000\",\n \"available_balance\": \"0.000000\",\n \"currency\": \"ETB\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"11696c59-070f-4a0e-95e4-98c0266f067e"},{"name":"Send SMS","id":"abc55283-4ca3-406c-9d11-1ba0d0933b55","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.iconicsms.et/api/v1/sms/send?token=&phone=phone number&msg=your message","description":"Example (GET)
\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n
https://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n
Replace 2519XXXXXXXX with the receiver and shortcode_id to choose the sender; without it the default shortcode is used.
\nQueues one SMS and returns 202 with data.message (id, status queued, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.
\n","urlObject":{"path":["api","v1","sms","send"],"host":["https://api.iconicsms.et"],"query":[{"description":{"content":"Your IconicSMS API key (starts with iconicsms_live_sk_ or iconicsms_test_sk_). Create one in the dashboard under API Keys. Test keys use the mock provider and are never delivered.
\n","type":"text/plain"},"key":"token","value":""},{"description":{"content":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.
\n","type":"text/plain"},"key":"phone","value":"phone number"},{"description":{"content":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).
\n","type":"text/plain"},"key":"msg","value":"your message"},{"disabled":true,"description":{"content":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.
\n","type":"text/plain"},"key":"shortcode_id","value":"your shortcode id"}],"variable":[]}},"response":[{"id":"ac80a771-ef7d-4301-b24c-51bce31aefec","name":"202 SMS queued","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/send?token=&phone=phone number&msg=your message","host":["https://api.iconicsms.et"],"path":["api","v1","sms","send"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments)."},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered."},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"message\": {\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"to\": \"+251911234567\",\n \"from\": \"ICONIC\",\n \"body\": \"Hello from IconicSMS\",\n \"status\": \"queued\",\n \"message_type\": \"sms\",\n \"segment_count\": 1,\n \"estimated_cost\": \"0.350000\",\n \"created_at\": \"2026-10-05T10:00:00+03:00\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"b110aeae-d3fa-4e28-870f-cbf18449a304","name":"401 Invalid API key","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/send?token=&phone=phone number&msg=your message","host":["https://api.iconicsms.et"],"path":["api","v1","sms","send"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments)."},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"5236848d-7427-44cc-a222-210e0e731839","name":"422 Invalid phone number","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/send?token=&phone=phone number&msg=your message","host":["https://api.iconicsms.et"],"path":["api","v1","sms","send"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments)."},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered."},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_recipient\",\n \"message\": \"Invalid recipient phone number.\",\n \"details\": {\n \"phone\": \"Use an Ethiopian mobile number starting with 2519.\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"10075024-bde3-4656-b32e-895599c4f056","name":"402 Insufficient balance","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.iconicsms.et/api/v1/sms/send?token=&phone=phone number&msg=your message","host":["https://api.iconicsms.et"],"path":["api","v1","sms","send"],"query":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered."},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted."},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments)."},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","disabled":true}]},"description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered."},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"insufficient_balance\",\n \"message\": \"Insufficient wallet balance to send this message.\",\n \"details\": {\n \"required_amount\": \"0.350000\",\n \"available_balance\": \"0.000000\",\n \"currency\": \"ETB\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"abc55283-4ca3-406c-9d11-1ba0d0933b55"}],"id":"fdc7a599-0edb-43ff-a298-ae82893de63d","description":"The same endpoints as GET requests: every parameter goes in the URL query string.
\n","_postman_id":"fdc7a599-0edb-43ff-a298-ae82893de63d"},{"name":"Send OTP","id":"e04e6b5b-8fc3-4ec7-b647-27bc98ee080e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with iconicsms_live_sk_ or iconicsms_test_sk_). Create one in the dashboard under API Keys. Test keys use the mock provider and are never delivered.
\n","type":"text"},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.
\n","type":"text","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.
\n","type":"text"},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put [[code]] where the code should appear, e.g. Your Tina verification code is [[code]] or Your reset verification code is [[code]]. If [[code]] is missing, the code is added at the end. If not specified: Your verification code is <code>. The code is always generated by IconicSMS (6 digits).
\n","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/otp","description":"Example (GET)
\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n
https://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n
Replace 2519XXXXXXXX with the receiver and [[code]] is replaced by the generated code.
\nGenerates a random 6-digit code, sends it to phone and returns 202 with data.code and data.message. Store the code (hashed, with an expiry) in your application and verify it there.
\n","urlObject":{"path":["api","v1","sms","otp"],"host":["https://api.iconicsms.et"],"query":[],"variable":[]}},"response":[{"id":"3d1d2baf-dd10-4f7a-b15f-15c2912dc337","name":"202 OTP queued","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put `[[code]]` where the code should appear, e.g. `Your Tina verification code is [[code]]` or `Your reset verification code is [[code]]`. If `[[code]]` is missing, the code is added at the end. If not specified: `Your verification code is `. The code is always generated by IconicSMS (6 digits).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/otp","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"message\": {\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"to\": \"+251911234567\",\n \"from\": \"ICONIC\",\n \"body\": \"Your Tina verification code is 482913\",\n \"status\": \"queued\",\n \"message_type\": \"otp\",\n \"segment_count\": 1,\n \"estimated_cost\": \"0.350000\",\n \"created_at\": \"2026-10-05T10:00:00+03:00\"\n },\n \"code\": \"482913\"\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"f3c14013-3b75-4ed8-8f6b-7ecb2b82e42b","name":"401 Invalid API key","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put `[[code]]` where the code should appear, e.g. `Your Tina verification code is [[code]]` or `Your reset verification code is [[code]]`. If `[[code]]` is missing, the code is added at the end. If not specified: `Your verification code is `. The code is always generated by IconicSMS (6 digits).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/otp","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"a41ad1f9-1f2e-4c3f-86eb-1d0154f86e58","name":"402 Insufficient balance","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"shortcode_id","value":"your shortcode_id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"phone","value":"your phone number","description":"The phone number of the OTP receiver. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"Your Tina verification code is [[code]]","description":"(optional) Your own OTP text. Put `[[code]]` where the code should appear, e.g. `Your Tina verification code is [[code]]` or `Your reset verification code is [[code]]`. If `[[code]]` is missing, the code is added at the end. If not specified: `Your verification code is `. The code is always generated by IconicSMS (6 digits).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/otp","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/otp?phone=2519XXXXXXXX&msg=Your%20Tina%20verification%20code%20is%20[[code]]&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. The second example uses your own text; `[[code]]` is replaced by the generated code.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `msg` | Optional | OTP text with `[[code]]`; defaults to `Your verification code is `. |\n\nGenerates a random 6-digit code, sends it to `phone` and returns `202` with `data.code` and `data.message`. Store the code (hashed, with an expiry) in your application and verify it there."},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"insufficient_balance\",\n \"message\": \"Insufficient wallet balance to send this message.\",\n \"details\": {\n \"required_amount\": \"0.350000\",\n \"available_balance\": \"0.000000\",\n \"currency\": \"ETB\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"e04e6b5b-8fc3-4ec7-b647-27bc98ee080e"},{"name":"Send SMS","id":"1ca0c577-e7b8-412c-a3c7-28e99760e758","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with iconicsms_live_sk_ or iconicsms_test_sk_). Create one in the dashboard under API Keys. Test keys use the mock provider and are never delivered.
\n","type":"text"},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.
\n","type":"text"},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).
\n","type":"text"},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.
\n","type":"text","disabled":true},{"key":"callback","value":"your webhook / callback url","description":"(optional) Your callback URL. It is stored on the message as callback_url. Status notifications are delivered to the webhook endpoints configured in the dashboard (see the request description).
\n","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/send","description":"Example (GET)
\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n
https://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n
Replace 2519XXXXXXXX with the receiver and shortcode_id to choose the sender; without it the default shortcode is used.
\nQueues one SMS and returns 202 with data.message (id, status queued, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.
\nStatus updates (message.queued, message.sent, message.delivered, message.failed, ...) are POSTed to the webhook endpoints you configure in the dashboard. This is an example request body of the webhook:
\n{\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-10-01T10:00:05+03:00\",\n \"livemode\": true,\n \"data\": {\n \"object\": \"message\",\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"status\": \"delivered\",\n \"from\": \"ICONIC\",\n \"to\": \"+251900000000\",\n \"client_reference\": null,\n \"provider\": \"sendet_gateway\",\n \"provider_message_id\": \"908703ee-3898-4b45-b0e9-6fb05d7619a5\",\n \"segment_count\": 1,\n \"encoding\": \"gsm7\",\n \"billing_status\": \"billed\",\n \"created_at\": \"2026-10-01 10:00:00.000000\",\n \"sent_at\": \"2026-10-01 10:00:01.000000\",\n \"delivered_at\": \"2026-10-01 10:00:05.000000\",\n \"undelivered_at\": null,\n \"expired_at\": null,\n \"last_dlr_status\": \"DELIVRD\"\n }\n}\n
\n","urlObject":{"path":["api","v1","sms","send"],"host":["https://api.iconicsms.et"],"query":[],"variable":[]}},"response":[{"id":"2c4ea3af-1ea1-4d5d-90a2-0c379e41014d","name":"202 SMS queued","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).","type":"text"},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"callback","value":"your webhook / callback url","description":"(optional) Your callback URL. It is stored on the message as `callback_url`. Status notifications are delivered to the webhook endpoints configured in the dashboard (see the request description).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/send","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.\n\nStatus updates (`message.queued`, `message.sent`, `message.delivered`, `message.failed`, ...) are POSTed to the webhook endpoints you configure in the dashboard. This is an example request body of the webhook:\n\n```json\n{\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-10-01T10:00:05+03:00\",\n \"livemode\": true,\n \"data\": {\n \"object\": \"message\",\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"status\": \"delivered\",\n \"from\": \"ICONIC\",\n \"to\": \"+251900000000\",\n \"client_reference\": null,\n \"provider\": \"sendet_gateway\",\n \"provider_message_id\": \"908703ee-3898-4b45-b0e9-6fb05d7619a5\",\n \"segment_count\": 1,\n \"encoding\": \"gsm7\",\n \"billing_status\": \"billed\",\n \"created_at\": \"2026-10-01 10:00:00.000000\",\n \"sent_at\": \"2026-10-01 10:00:01.000000\",\n \"delivered_at\": \"2026-10-01 10:00:05.000000\",\n \"undelivered_at\": null,\n \"expired_at\": null,\n \"last_dlr_status\": \"DELIVRD\"\n }\n}\n```"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"message\": {\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"to\": \"+251911234567\",\n \"from\": \"ICONIC\",\n \"body\": \"Hello from IconicSMS\",\n \"status\": \"queued\",\n \"message_type\": \"sms\",\n \"segment_count\": 1,\n \"estimated_cost\": \"0.350000\",\n \"created_at\": \"2026-10-05T10:00:00+03:00\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"80ea9e57-be49-4315-8f87-bd0e4303a183","name":"401 Invalid API key","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).","type":"text"},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"callback","value":"your webhook / callback url","description":"(optional) Your callback URL. It is stored on the message as `callback_url`. Status notifications are delivered to the webhook endpoints configured in the dashboard (see the request description).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/send","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.\n\nStatus updates (`message.queued`, `message.sent`, `message.delivered`, `message.failed`, ...) are POSTed to the webhook endpoints you configure in the dashboard. This is an example request body of the webhook:\n\n```json\n{\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-10-01T10:00:05+03:00\",\n \"livemode\": true,\n \"data\": {\n \"object\": \"message\",\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"status\": \"delivered\",\n \"from\": \"ICONIC\",\n \"to\": \"+251900000000\",\n \"client_reference\": null,\n \"provider\": \"sendet_gateway\",\n \"provider_message_id\": \"908703ee-3898-4b45-b0e9-6fb05d7619a5\",\n \"segment_count\": 1,\n \"encoding\": \"gsm7\",\n \"billing_status\": \"billed\",\n \"created_at\": \"2026-10-01 10:00:00.000000\",\n \"sent_at\": \"2026-10-01 10:00:01.000000\",\n \"delivered_at\": \"2026-10-01 10:00:05.000000\",\n \"undelivered_at\": null,\n \"expired_at\": null,\n \"last_dlr_status\": \"DELIVRD\"\n }\n}\n```"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"fe56c6f8-cde7-45d1-b3e5-c058986572b8","name":"422 Invalid phone number","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).","type":"text"},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"callback","value":"your webhook / callback url","description":"(optional) Your callback URL. It is stored on the message as `callback_url`. Status notifications are delivered to the webhook endpoints configured in the dashboard (see the request description).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/send","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.\n\nStatus updates (`message.queued`, `message.sent`, `message.delivered`, `message.failed`, ...) are POSTed to the webhook endpoints you configure in the dashboard. This is an example request body of the webhook:\n\n```json\n{\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-10-01T10:00:05+03:00\",\n \"livemode\": true,\n \"data\": {\n \"object\": \"message\",\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"status\": \"delivered\",\n \"from\": \"ICONIC\",\n \"to\": \"+251900000000\",\n \"client_reference\": null,\n \"provider\": \"sendet_gateway\",\n \"provider_message_id\": \"908703ee-3898-4b45-b0e9-6fb05d7619a5\",\n \"segment_count\": 1,\n \"encoding\": \"gsm7\",\n \"billing_status\": \"billed\",\n \"created_at\": \"2026-10-01 10:00:00.000000\",\n \"sent_at\": \"2026-10-01 10:00:01.000000\",\n \"delivered_at\": \"2026-10-01 10:00:05.000000\",\n \"undelivered_at\": null,\n \"expired_at\": null,\n \"last_dlr_status\": \"DELIVRD\"\n }\n}\n```"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_recipient\",\n \"message\": \"Invalid recipient phone number.\",\n \"details\": {\n \"phone\": \"Use an Ethiopian mobile number starting with 2519.\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"d8f2a7f7-f442-4cfa-a882-7e7cef369f5c","name":"402 Insufficient balance","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with `iconicsms_live_sk_` or `iconicsms_test_sk_`). Create one in the dashboard under **API Keys**. Test keys use the mock provider and are never delivered.","type":"text"},{"key":"phone","value":"phone number","description":"The receiver phone number. Must start with 2519 (e.g. 2519XXXXXXXX); +2519…, 09… and 2517… are also accepted.","type":"text"},{"key":"msg","value":"your message","description":"Message content. Supports Unicode (Amharic). Long messages are split into segments and billed per segment (max 10 segments).","type":"text"},{"key":"shortcode_id","value":"your shortcode id","description":"(optional) The sender (shortcode) to send from: the id or the text of an approved sender name of your organization. If not specified, the default shortcode is used: your organization's approved sender name, or the IconicSMS shortcode when your organization has none.","type":"text","disabled":true},{"key":"callback","value":"your webhook / callback url","description":"(optional) Your callback URL. It is stored on the message as `callback_url`. Status notifications are delivered to the webhook endpoints configured in the dashboard (see the request description).","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/sms/send","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&token=\n```\n\n```\nhttps://api.iconicsms.et/api/v1/sms/send?msg=Hello%20from%20IconicSMS&phone=2519XXXXXXXX&shortcode_id=YOURSENDER&token=\n```\n\nReplace `2519XXXXXXXX` with the receiver and `` with your API key. Add `shortcode_id` to choose the sender; without it the default shortcode is used.\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key. |\n| `phone` | Required | Receiver, starting with 2519 (2519XXXXXXXX). |\n| `msg` | Required | Message text (Unicode/Amharic supported). |\n| `shortcode_id` | Optional | Sender to use; defaults to your default shortcode. |\n\nQueues one SMS and returns `202` with `data.message` (id, status `queued`, to, from, segment_count, estimated_cost). A 2xx response means queued, not yet delivered.\n\nStatus updates (`message.queued`, `message.sent`, `message.delivered`, `message.failed`, ...) are POSTed to the webhook endpoints you configure in the dashboard. This is an example request body of the webhook:\n\n```json\n{\n \"type\": \"message.delivered\",\n \"created_at\": \"2026-10-01T10:00:05+03:00\",\n \"livemode\": true,\n \"data\": {\n \"object\": \"message\",\n \"id\": \"0b9a6f1e-5c1d-4b7e-9a51-3f4a2d7c8e90\",\n \"status\": \"delivered\",\n \"from\": \"ICONIC\",\n \"to\": \"+251900000000\",\n \"client_reference\": null,\n \"provider\": \"sendet_gateway\",\n \"provider_message_id\": \"908703ee-3898-4b45-b0e9-6fb05d7619a5\",\n \"segment_count\": 1,\n \"encoding\": \"gsm7\",\n \"billing_status\": \"billed\",\n \"created_at\": \"2026-10-01 10:00:00.000000\",\n \"sent_at\": \"2026-10-01 10:00:01.000000\",\n \"delivered_at\": \"2026-10-01 10:00:05.000000\",\n \"undelivered_at\": null,\n \"expired_at\": null,\n \"last_dlr_status\": \"DELIVRD\"\n }\n}\n```"},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"insufficient_balance\",\n \"message\": \"Insufficient wallet balance to send this message.\",\n \"details\": {\n \"required_amount\": \"0.350000\",\n \"available_balance\": \"0.000000\",\n \"currency\": \"ETB\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"1ca0c577-e7b8-412c-a3c7-28e99760e758"},{"name":"Send Bulk","id":"2a4bf0c7-1430-4482-a5a2-728d7a928292","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"\",\n \"contacts\": [\n {\n \"fname\": \"contact first name (optional)\",\n \"lname\": \"contact last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n },\n {\n \"fname\": \"contact 2 first name (optional)\",\n \"lname\": \"contact 2 last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n }\n ],\n \"sender_id\": \"\",\n \"msg\": \"Your Message add [[fname]] or [[lname]] as template. (Required)\",\n \"notify_url\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.iconicsms.et/api/v1/sms/send/bulk","description":"Example
\ncurl -X POST 'https://api.iconicsms.et/api/v1/sms/send/bulk' \\\n -H 'Content-Type: application/json' \\\n -H 'X-IconicSMS-Key: ' \\\n -d '{\"contacts\":[{\"fname\":\"Abebe\",\"phone_number\":\"2519XXXXXXXX\"}],\"msg\":\"Hello [[fname]]\"}'\n
Only token, contacts[].phone_number and msg are required; the other fields in the sample body are optional. [[fname]] and [[lname]] in msg are replaced per contact. Your wallet must cover the whole batch, otherwise nothing is sent (402). Invalid contacts are listed in data.rejected and the rest are sent.
\n","urlObject":{"path":["api","v1","sms","send","bulk"],"host":["https://api.iconicsms.et"],"query":[],"variable":[]}},"response":[{"id":"597e8f8f-1f54-411c-b4bc-ef301093725d","name":"202 Batch queued","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"\",\n \"contacts\": [\n {\n \"fname\": \"contact first name (optional)\",\n \"lname\": \"contact last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n },\n {\n \"fname\": \"contact 2 first name (optional)\",\n \"lname\": \"contact 2 last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n }\n ],\n \"sender_id\": \"\",\n \"msg\": \"Your Message add [[fname]] or [[lname]] as template. (Required)\",\n \"notify_url\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.iconicsms.et/api/v1/sms/send/bulk","description":"**Example**\n\n```\ncurl -X POST 'https://api.iconicsms.et/api/v1/sms/send/bulk' \\\n -H 'Content-Type: application/json' \\\n -H 'X-IconicSMS-Key: ' \\\n -d '{\"contacts\":[{\"fname\":\"Abebe\",\"phone_number\":\"2519XXXXXXXX\"}],\"msg\":\"Hello [[fname]]\"}'\n```\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key (or send the `X-IconicSMS-Key` header). |\n| `contacts` | Required | List of contacts, at most 1000 per request. |\n| `contacts[].phone_number` | Required | Receiver, starting with 2519. |\n| `contacts[].fname` | Optional | Replaces `[[fname]]` in `msg`. |\n| `contacts[].lname` | Optional | Replaces `[[lname]]` in `msg`. |\n| `msg` | Required | Message text; may contain `[[fname]]` and `[[lname]]`. |\n| `sender_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `notify_url` | Optional | Callback URL stored on every message of the batch. |\n\nOnly `token`, `contacts[].phone_number` and `msg` are required; the other fields in the sample body are optional. `[[fname]]` and `[[lname]]` in `msg` are replaced per contact. Your wallet must cover the whole batch, otherwise nothing is sent (`402`). Invalid contacts are listed in `data.rejected` and the rest are sent."},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"total_contacts\": 2,\n \"accepted_count\": 1,\n \"rejected_count\": 1,\n \"estimated_cost\": \"0.350000\",\n \"currency\": \"ETB\",\n \"messages\": [\n {\n \"index\": 0,\n \"phone_number\": \"251911000001\",\n \"message_id\": \"8e6c45b9-06a8-4ce7-9d7d-9ada4c6863f8\",\n \"to\": \"+251911000001\",\n \"status\": \"queued\",\n \"segment_count\": 1,\n \"estimated_cost\": \"0.350000\"\n }\n ],\n \"rejected\": [\n {\n \"index\": 1,\n \"phone_number\": \"0912\",\n \"error_code\": \"invalid_recipient\",\n \"message\": \"Invalid recipient phone number.\"\n }\n ]\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"1df5c1c7-6120-4aab-a7ea-1b4b73033972","name":"402 Balance does not cover the batch","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"\",\n \"contacts\": [\n {\n \"fname\": \"contact first name (optional)\",\n \"lname\": \"contact last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n },\n {\n \"fname\": \"contact 2 first name (optional)\",\n \"lname\": \"contact 2 last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n }\n ],\n \"sender_id\": \"\",\n \"msg\": \"Your Message add [[fname]] or [[lname]] as template. (Required)\",\n \"notify_url\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.iconicsms.et/api/v1/sms/send/bulk","description":"**Example**\n\n```\ncurl -X POST 'https://api.iconicsms.et/api/v1/sms/send/bulk' \\\n -H 'Content-Type: application/json' \\\n -H 'X-IconicSMS-Key: ' \\\n -d '{\"contacts\":[{\"fname\":\"Abebe\",\"phone_number\":\"2519XXXXXXXX\"}],\"msg\":\"Hello [[fname]]\"}'\n```\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key (or send the `X-IconicSMS-Key` header). |\n| `contacts` | Required | List of contacts, at most 1000 per request. |\n| `contacts[].phone_number` | Required | Receiver, starting with 2519. |\n| `contacts[].fname` | Optional | Replaces `[[fname]]` in `msg`. |\n| `contacts[].lname` | Optional | Replaces `[[lname]]` in `msg`. |\n| `msg` | Required | Message text; may contain `[[fname]]` and `[[lname]]`. |\n| `sender_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `notify_url` | Optional | Callback URL stored on every message of the batch. |\n\nOnly `token`, `contacts[].phone_number` and `msg` are required; the other fields in the sample body are optional. `[[fname]]` and `[[lname]]` in `msg` are replaced per contact. Your wallet must cover the whole batch, otherwise nothing is sent (`402`). Invalid contacts are listed in `data.rejected` and the rest are sent."},"status":"Payment Required","code":402,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"insufficient_balance\",\n \"message\": \"Insufficient wallet balance to send this batch.\",\n \"details\": {\n \"required_amount\": \"14.000000\",\n \"available_balance\": \"5.000000\",\n \"currency\": \"ETB\",\n \"message_count\": \"40\"\n }\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"22841a41-4934-4ee3-b887-53c1fc0a7507","name":"401 Invalid API key","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"token\": \"\",\n \"contacts\": [\n {\n \"fname\": \"contact first name (optional)\",\n \"lname\": \"contact last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n },\n {\n \"fname\": \"contact 2 first name (optional)\",\n \"lname\": \"contact 2 last name (optional)\",\n \"phone_number\": \"contact phone number (required)\"\n }\n ],\n \"sender_id\": \"\",\n \"msg\": \"Your Message add [[fname]] or [[lname]] as template. (Required)\",\n \"notify_url\": \"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.iconicsms.et/api/v1/sms/send/bulk","description":"**Example**\n\n```\ncurl -X POST 'https://api.iconicsms.et/api/v1/sms/send/bulk' \\\n -H 'Content-Type: application/json' \\\n -H 'X-IconicSMS-Key: ' \\\n -d '{\"contacts\":[{\"fname\":\"Abebe\",\"phone_number\":\"2519XXXXXXXX\"}],\"msg\":\"Hello [[fname]]\"}'\n```\n\n| Parameter | | Description |\n|---|---|---|\n| `token` | Required | Your API key (or send the `X-IconicSMS-Key` header). |\n| `contacts` | Required | List of contacts, at most 1000 per request. |\n| `contacts[].phone_number` | Required | Receiver, starting with 2519. |\n| `contacts[].fname` | Optional | Replaces `[[fname]]` in `msg`. |\n| `contacts[].lname` | Optional | Replaces `[[lname]]` in `msg`. |\n| `msg` | Required | Message text; may contain `[[fname]]` and `[[lname]]`. |\n| `sender_id` | Optional | Sender to use; defaults to your default shortcode. |\n| `notify_url` | Optional | Callback URL stored on every message of the batch. |\n\nOnly `token`, `contacts[].phone_number` and `msg` are required; the other fields in the sample body are optional. `[[fname]]` and `[[lname]]` in `msg` are replaced per contact. Your wallet must cover the whole batch, otherwise nothing is sent (`402`). Invalid contacts are listed in `data.rejected` and the rest are sent."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"2a4bf0c7-1430-4482-a5a2-728d7a928292"},{"name":"Get Balance of API Key","id":"8e29fdce-68e0-40bf-9ad8-ed49512f56da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"X-IconicSMS-Key","value":"","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"token","value":"","description":"Your IconicSMS API key (starts with iconicsms_live_sk_ or iconicsms_test_sk_). Create one in the dashboard under API Keys. Test keys use the mock provider and are never delivered.
\n","type":"text"},{"key":"billing_id","value":"your billing_id","description":"(optional) Your billing id (your organization id). If not specified, the billing associated with the API token is used. A billing id that does not belong to the token returns 404. On GET it can also be sent as a query parameter.
\n","type":"text","disabled":true}]},"url":"https://api.iconicsms.et/api/v1/balance","description":"Example (GET)
\nhttps://api.iconicsms.et/api/v1/balance?token=\n
or with the header:
\ncurl 'https://api.iconicsms.et/api/v1/balance' -H 'X-IconicSMS-Key: '\n
Returns the wallet balance of the API key's organization: data.billing_id, data.available_balance, data.reserved_balance and data.currency.
\n","urlObject":{"path":["api","v1","balance"],"host":["https://api.iconicsms.et"],"query":[],"variable":[]}},"response":[{"id":"dc4b4984-c15b-4f76-846d-0b378ee13033","name":"200 Balance","originalRequest":{"method":"GET","header":[{"key":"X-IconicSMS-Key","value":"","type":"text"}],"url":"https://api.iconicsms.et/api/v1/balance","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/balance?token=\n```\n\nor with the header:\n\n```\ncurl 'https://api.iconicsms.et/api/v1/balance' -H 'X-IconicSMS-Key: '\n```\n\n| Parameter | | Description |\n|---|---|---|\n| `X-IconicSMS-Key header or token` | Required | Your API key. |\n| `billing_id` | Optional | Your organization id; defaults to the API key's organization. |\n\nReturns the wallet balance of the API key's organization: `data.billing_id`, `data.available_balance`, `data.reserved_balance` and `data.currency`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"billing_id\": \"0622933c-e1a5-4c9c-8491-603c6caf7131\",\n \"available_balance\": \"125.500000\",\n \"reserved_balance\": \"0.000000\",\n \"currency\": \"ETB\"\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"},{"id":"ab396548-158c-4484-86fe-2295b903963b","name":"401 Invalid API key","originalRequest":{"method":"GET","header":[{"key":"X-IconicSMS-Key","value":"","type":"text"}],"url":"https://api.iconicsms.et/api/v1/balance","description":"**Example (GET)**\n\n```\nhttps://api.iconicsms.et/api/v1/balance?token=\n```\n\nor with the header:\n\n```\ncurl 'https://api.iconicsms.et/api/v1/balance' -H 'X-IconicSMS-Key: '\n```\n\n| Parameter | | Description |\n|---|---|---|\n| `X-IconicSMS-Key header or token` | Required | Your API key. |\n| `billing_id` | Optional | Your organization id; defaults to the API key's organization. |\n\nReturns the wallet balance of the API key's organization: `data.billing_id`, `data.available_balance`, `data.reserved_balance` and `data.currency`."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": false,\n \"error\": {\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid or missing API key.\",\n \"details\": []\n },\n \"meta\": {\n \"request_id\": \"req_6f1c2b7e9a0d4c3b8e5f1a2b3c4d5e6f\"\n }\n}"}],"_postman_id":"8e29fdce-68e0-40bf-9ad8-ed49512f56da"}],"variable":[{"key":"base_url","value":"https://api.iconicsms.et"},{"key":"token","value":""}]}