{ "openapi": "3.1.0", "info": { "title": "SwalaSMS Developer API", "version": "1.0.0", "description": "SwalaSMS Developer API lets your system send and track SMS messages through the same routing, sender ID, wallet, spam-control, and country-credit rules used by the web portal.\n\nUse a sandbox API key while testing. Sandbox keys return realistic queued\/delivered responses but never send real SMS or consume SMS credits. Use a live key only after your sender IDs, SMS route, wallet balance, and provider credits are ready.\n\nEvery request must include `Authorization: Bearer YOUR_API_KEY`. Send endpoints also support `Idempotency-Key`; pass a stable unique value from your own system when retrying a request so the same SMS is not queued twice.\n\nPhone numbers should be sent in E.164 format, for example `+255712345678`. A successful send returns `202 Accepted` because delivery is queued and processed asynchronously. Use the status endpoint to check the current state of a message.\n\nCommon statuses are `queued`, `processing`, `sent`, `delivered`, `failed`, and `scheduled`. Validation, sender ID, route, wallet, provider-credit, spam-policy, and recipient opt-out errors return JSON with `success: false` and a readable `message`." }, "servers": [ { "url": "https:\/\/swalasms.co.tz\/api\/v1", "description": "SwalaSMS API v1" } ], "tags": [ { "name": "Messaging", "description": "Send messages and check delivery and balance." }, { "name": "Sender IDs", "description": "Request a sender ID and track its approval. Mirrors the web flow exactly." }, { "name": "Account", "description": "Who the key belongs to, which routes are verified, and what is left to spend." } ], "paths": { "\/balance": { "get": { "operationId": "v1.balance", "description": "Return the customer SMS credit balance for the API key owner.\n\nThe top-level `balance` is the total available SMS units across all enabled country wallets. The `countries` array breaks the balance down per country with wallet UID, ISO country code, calling code, and remaining SMS units.\n\nUse this endpoint before sending if your application needs to warn users before a campaign is queued. The actual send endpoints still perform the final wallet and provider-credit checks inside a database transaction.", "summary": "Check SMS balance", "tags": [ "Messaging" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "object", "properties": { "balance": { "type": "string" }, "currency": { "type": "string", "const": "SMS" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "wallet_uid": { "type": "string" }, "country": { "type": "string" }, "calling_code": { "type": [ "string", "null" ] }, "balance": { "type": "string" } }, "required": [ "wallet_uid", "country", "calling_code", "balance" ] } } }, "required": [ "balance", "currency", "countries" ] } }, "required": [ "success", "request_uid", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "mode": { "type": "string", "const": "sandbox" }, "data": { "type": "object", "properties": { "wallet_uid": { "type": "string", "const": "sandbox_wallet" }, "balance": { "type": "integer", "const": 100000 }, "currency": { "type": "string", "const": "SMS" } }, "required": [ "wallet_uid", "balance", "currency" ] } }, "required": [ "success", "request_uid", "mode", "data" ] } ] } } } } } } }, "\/sms\/messages": { "post": { "operationId": "sms.messages.send", "description": "Queue one SMS for delivery through the active SwalaSMS routing engine, under the same rules a message gets when it is composed in the portal. Nothing is relaxed because the request arrived over the API.\n\nThe API key owner must have an active account, an approved sender ID assigned to the account, a verified SMS route for the destination country, enough customer SMS credit, and an available provider route with provider credit. The message body is checked by the spam policy before it is accepted.\n\nSend `recipient` in E.164 format, for example `+255712345678`. Include `Idempotency-Key` when retrying from your application; if the same key was already accepted, SwalaSMS returns the existing message instead of creating a duplicate.\n\nSuccessful requests return `202 Accepted` because the SMS is queued and delivered asynchronously. The response carries the message `uid` for your own records; delivery outcomes arrive at your configured webhook.\n\nFor one message to many recipients, use `POST \/api\/v1\/sms\/send-bulk`. Repeating the same body and sender through this single-message endpoint is rate-limited.", "summary": "Send a single SMS", "tags": [ "Messaging" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "pattern": "^\\+?[0-9][0-9 ()\\.\\-]*$", "maxLength": 32 }, "sender_id": { "type": "string", "maxLength": 32 }, "body": { "type": "string", "maxLength": 1600 } }, "required": [ "recipient", "sender_id", "body" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "sms.messages.index", "description": "Every message this account has sent, newest first, with what became of it.\n\nA send returns `queued`: the carrier decides delivery seconds or minutes later, so this is how an integration finds out. Poll it, or read one message directly with `GET \/sms\/messages\/{uid}` using the `uid` the send returned.\n\nFilter with `status` (`queued`, `sent`, `delivered`, `failed`), `channel` (`api` or `web`, to separate your integration's traffic from messages staff sent in the portal), and `from` \/ `to` as dates. `per_page` defaults to 50 and is capped at 100.\n\nEach entry carries `status`, `queued_at`, `sent_at`, `delivered_at`, `failure_reason` and the billed `units`.", "summary": "List messages and their delivery status", "tags": [ "Messaging" ], "parameters": [ { "name": "channel", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "required": [ "current_page", "per_page", "total", "last_page" ] } }, "required": [ "success", "request_uid", "data", "meta" ] } } } } } } }, "\/sms\/quick-message": { "post": { "operationId": "sms.quick-message.send", "description": "Queue one SMS for delivery through the active SwalaSMS routing engine, under the same rules a message gets when it is composed in the portal. Nothing is relaxed because the request arrived over the API.\n\nThe API key owner must have an active account, an approved sender ID assigned to the account, a verified SMS route for the destination country, enough customer SMS credit, and an available provider route with provider credit. The message body is checked by the spam policy before it is accepted.\n\nSend `recipient` in E.164 format, for example `+255712345678`. Include `Idempotency-Key` when retrying from your application; if the same key was already accepted, SwalaSMS returns the existing message instead of creating a duplicate.\n\nSuccessful requests return `202 Accepted` because the SMS is queued and delivered asynchronously. The response carries the message `uid` for your own records; delivery outcomes arrive at your configured webhook.\n\nFor one message to many recipients, use `POST \/api\/v1\/sms\/send-bulk`. Repeating the same body and sender through this single-message endpoint is rate-limited.", "summary": "Send a single SMS", "tags": [ "Messaging" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "pattern": "^\\+?[0-9][0-9 ()\\.\\-]*$", "maxLength": 32 }, "sender_id": { "type": "string", "maxLength": 32 }, "body": { "type": "string", "maxLength": 1600 } }, "required": [ "recipient", "sender_id", "body" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sms\/send-bulk": { "post": { "operationId": "sms.send-bulk", "description": "Queue the same SMS body to many recipients in one API call.\n\nUse this endpoint when your application already has the recipient list and each number is ready in E.164 format. The request accepts up to 1000 recipients. SwalaSMS still creates one local message per recipient so balance, reports, idempotency and delivery webhooks keep working the same way as the portal.\n\nThe payload mirrors provider bulk APIs: send `recipients`, `message`, `sender_id`, optional `campaign_name`, and optional `scheduled_at`.\n\nSuccessful requests return campaign-level counts. A recipient can still be skipped if its route, wallet, sender ID, provider credit or spam checks fail.", "summary": "Send bulk SMS", "tags": [ "Messaging" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string", "pattern": "^\\+?[0-9][0-9 ()\\.\\-]*$", "maxLength": 32 }, "minItems": 1, "maxItems": 1000 }, "sender_id": { "type": "string", "maxLength": 32 }, "body": { "type": "string", "maxLength": 1600 }, "message": { "type": [ "string", "null" ], "maxLength": 1600 }, "name": { "type": [ "string", "null" ], "maxLength": 120 }, "campaign_name": { "type": [ "string", "null" ], "maxLength": 120 }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "recipients", "sender_id", "body" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "202": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "mode": { "type": "string", "const": "sandbox" }, "data": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "queued" ] }, "recipient_count": { "type": "integer" }, "queued_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "scheduled_at": { "type": [ "string", "null" ] } }, "required": [ "uid", "name", "status", "recipient_count", "queued_count", "failed_count", "scheduled_at" ] } }, "required": [ "success", "request_uid", "mode", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sms\/messages\/{uid}": { "get": { "operationId": "sms.messages.show", "description": "The delivery status of a single message, by the `uid` the send returned.\n\n`status` moves `queued` \u2192 `sent` \u2192 `delivered`, or ends at `failed` with a `failure_reason` written for a person. `delivered_at` is set the moment the carrier confirms it. The response carries the queued, sent, delivered and failure timestamps when they are known; which provider carried the message is not exposed.\n\nAn invalid UID is answered with a validation error, and a valid one belonging to another account with `404` \u2014 the two are told apart deliberately, so a wrong id is a mistake to fix rather than a hint about somebody else's traffic.\n\nA sandbox key answers `delivered` immediately without looking anything up, so an integration can be built end to end before a real message is ever sent.", "summary": "Check one message", "tags": [ "Messaging" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "request_uid", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "mode": { "type": "string", "const": "sandbox" }, "data": { "type": "object", "properties": { "uid": { "type": "string" }, "status": { "type": "string", "const": "delivered" }, "delivered_at": { "type": "string" } }, "required": [ "uid", "status", "delivered_at" ] } }, "required": [ "success", "request_uid", "mode", "data" ] } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "message": { "type": "string", "const": "SMS message was not found for this API key." } }, "required": [ "success", "request_uid", "message" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "message": { "type": "string", "const": "Message UID must be a valid UUID." } }, "required": [ "success", "request_uid", "message" ] } } } } } } }, "\/sms\/balance": { "get": { "operationId": "sms.balance", "description": "Return the customer SMS credit balance for the API key owner.\n\nThe top-level `balance` is the total available SMS units across all enabled country wallets. The `countries` array breaks the balance down per country with wallet UID, ISO country code, calling code, and remaining SMS units.\n\nUse this endpoint before sending if your application needs to warn users before a campaign is queued. The actual send endpoints still perform the final wallet and provider-credit checks inside a database transaction.", "summary": "Check SMS balance", "tags": [ "Messaging" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "object", "properties": { "balance": { "type": "string" }, "currency": { "type": "string", "const": "SMS" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "wallet_uid": { "type": "string" }, "country": { "type": "string" }, "calling_code": { "type": [ "string", "null" ] }, "balance": { "type": "string" } }, "required": [ "wallet_uid", "country", "calling_code", "balance" ] } } }, "required": [ "balance", "currency", "countries" ] } }, "required": [ "success", "request_uid", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "mode": { "type": "string", "const": "sandbox" }, "data": { "type": "object", "properties": { "wallet_uid": { "type": "string", "const": "sandbox_wallet" }, "balance": { "type": "integer", "const": 100000 }, "currency": { "type": "string", "const": "SMS" } }, "required": [ "wallet_uid", "balance", "currency" ] } }, "required": [ "success", "request_uid", "mode", "data" ] } ] } } } } } } }, "\/sender-ids": { "get": { "operationId": "v1.sender-ids.index", "description": "Every sender ID this account can send with, plus every request it has made, at any status.\n\nUse this to poll a request submitted with `POST \/sender-ids`. A sender ID may only be used for sending once `is_usable` is `true` (`status` is `approved`). When a request was turned down, `rejection_reason` explains why.\n\nStatuses: `pending`, `approved`, `rejected`, `suspended`.", "summary": "List sender IDs", "tags": [ "Sender IDs" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "request_uid", "data" ] } } } } } }, "post": { "operationId": "v1.sender-ids.store", "description": "Submits a sender ID for manual review. Applies exactly the same gates as the web form, so anything refused here would have been refused there.\n\n**Attaching documents.** Every requirement from `GET \/sender-ids\/requirements` with `is_required: true` must be present, either way:\n\n- JSON: `documents_base64: [{ \"requirement_uid\": \"\u2026\", \"filename\": \"certificate.pdf\", \"content_base64\": \"\u2026\" }]`\n- Multipart: a file part named `documents[]`\n\nAccepted formats are pdf, jpg, jpeg and png, up to 5 MB each.\n\n**Errors.**\n\n| Status | `error` | Meaning |\n| --- | --- | --- |\n| 422 | `sender_id_not_eligible` | Not enough SMS credits purchased yet. |\n| 422 | `route_not_verified` | No verified SMS route for that country. |\n| 422 | `country_not_available` | That country is not open on this platform. |\n| 409 | `sender_id_already_requested` | This name already exists for this country. Poll `GET \/sender-ids` instead; retrying never succeeds. |\n\nApproval is manual. Poll `GET \/sender-ids` until `is_usable` is `true`.", "summary": "Request a sender ID", "tags": [ "Sender IDs" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "description": "The same rules the web form applies, including the document requirements an\nadministrator has marked mandatory.\n\nDocuments may arrive two ways: as multipart files (what a browser sends) or\nas base64 inside a JSON body (what a script or an agent finds easiest). Both\nend up on the same disk in the same shape.", "properties": { "sender_id": { "type": "string" }, "country_uid": { "type": "string", "format": "uuid" }, "sample_message": { "type": "string", "minLength": 50, "maxLength": 500 }, "purpose": { "type": "string", "enum": [ "Notification", "Transactional", "OTP \/ Verification", "Promotional", "Marketing", "Alerts & Reminders", "Other" ] }, "documents": { "type": [ "array", "null" ], "items": { "type": "string" } }, "documents_base64": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "requirement_uid": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 180 }, "content_base64": { "type": "string" } }, "required": [ "requirement_uid", "filename", "content_base64" ] } } }, "required": [ "sender_id", "country_uid", "sample_message", "purpose" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "request_uid", "message", "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "error": { "type": "string", "const": "sender_id_already_requested" }, "message": { "type": "string" } }, "required": [ "success", "request_uid", "error", "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sms\/sender-ids": { "get": { "operationId": "sms.sender-ids.index", "description": "Every sender ID this account can send with, plus every request it has made, at any status.\n\nUse this to poll a request submitted with `POST \/sender-ids`. A sender ID may only be used for sending once `is_usable` is `true` (`status` is `approved`). When a request was turned down, `rejection_reason` explains why.\n\nStatuses: `pending`, `approved`, `rejected`, `suspended`.", "summary": "List sender IDs", "tags": [ "Sender IDs" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "request_uid", "data" ] } } } } } }, "post": { "operationId": "sms.sender-ids.store", "description": "Submits a sender ID for manual review. Applies exactly the same gates as the web form, so anything refused here would have been refused there.\n\n**Attaching documents.** Every requirement from `GET \/sender-ids\/requirements` with `is_required: true` must be present, either way:\n\n- JSON: `documents_base64: [{ \"requirement_uid\": \"\u2026\", \"filename\": \"certificate.pdf\", \"content_base64\": \"\u2026\" }]`\n- Multipart: a file part named `documents[]`\n\nAccepted formats are pdf, jpg, jpeg and png, up to 5 MB each.\n\n**Errors.**\n\n| Status | `error` | Meaning |\n| --- | --- | --- |\n| 422 | `sender_id_not_eligible` | Not enough SMS credits purchased yet. |\n| 422 | `route_not_verified` | No verified SMS route for that country. |\n| 422 | `country_not_available` | That country is not open on this platform. |\n| 409 | `sender_id_already_requested` | This name already exists for this country. Poll `GET \/sender-ids` instead; retrying never succeeds. |\n\nApproval is manual. Poll `GET \/sender-ids` until `is_usable` is `true`.", "summary": "Request a sender ID", "tags": [ "Sender IDs" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "description": "The same rules the web form applies, including the document requirements an\nadministrator has marked mandatory.\n\nDocuments may arrive two ways: as multipart files (what a browser sends) or\nas base64 inside a JSON body (what a script or an agent finds easiest). Both\nend up on the same disk in the same shape.", "properties": { "sender_id": { "type": "string" }, "country_uid": { "type": "string", "format": "uuid" }, "sample_message": { "type": "string", "minLength": 50, "maxLength": 500 }, "purpose": { "type": "string", "enum": [ "Notification", "Transactional", "OTP \/ Verification", "Promotional", "Marketing", "Alerts & Reminders", "Other" ] }, "documents": { "type": [ "array", "null" ], "items": { "type": "string" } }, "documents_base64": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "requirement_uid": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 180 }, "content_base64": { "type": "string" } }, "required": [ "requirement_uid", "filename", "content_base64" ] } } }, "required": [ "sender_id", "country_uid", "sample_message", "purpose" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "request_uid", "message", "data" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "error": { "type": "string", "const": "sender_id_already_requested" }, "message": { "type": "string" } }, "required": [ "success", "request_uid", "error", "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sms\/profile": { "get": { "operationId": "sms.profile.show", "description": "Returns the account, its verified SMS routes and the credit balance held\nfor each country.", "summary": "Read the account profile", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "phone_verified_at": { "type": [ "string", "null" ] }, "country": { "type": [ "object", "null" ], "properties": { "uid": { "type": "string" }, "iso2": { "type": "string" }, "calling_code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "uid", "iso2", "calling_code", "name" ] }, "balances": { "type": "array", "items": { "type": "object", "properties": { "wallet_uid": { "type": "string" }, "country_uid": { "type": "string" }, "country": { "type": "string" }, "calling_code": { "type": [ "string", "null" ] }, "balance": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "wallet_uid", "country_uid", "country", "calling_code", "balance", "currency" ] } }, "routes": { "type": "string" } }, "required": [ "uid", "name", "email", "phone", "phone_verified_at", "country", "balances", "routes" ] } }, "required": [ "success", "request_uid", "data" ] } } } } } } }, "\/sender-ids\/requirements": { "get": { "operationId": "v1.sender-ids.requirements", "description": "Call this **before** requesting a sender ID. It returns everything that decides whether a request will be accepted, and those rules differ per platform and per account.\n\n- `eligibility.can_request` \u2014 `false` means the account has not bought enough SMS credits yet. `required_units` and `minimum_purchase_amount` say how much is needed. Do not attempt the request.\n- `countries[]` \u2014 the only countries this account may request for. A country appears here once a phone number has been verified for it under SMS Routes, because a sender ID is registered per country.\n- `documents[]` \u2014 every entry with `is_required: true` must be attached when you request. Use its `uid`.\n- `sender_id_rules` \u2014 3 to 11 characters of letters, numbers and single spaces between words, and a list of reserved words that are always refused. Case is yours to choose and is carried through to the handset.\n- `purposes` \u2014 the allowed purpose values; send exactly one as `purpose`.\n- `sample_message_rules` \u2014 50 to 500 characters.", "summary": "Get sender ID requirements", "tags": [ "Sender IDs" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "object", "properties": { "eligibility": { "type": "object", "properties": { "can_request": { "type": "boolean" }, "purchased_units": { "type": "integer" }, "required_units": { "type": "integer" }, "currency": { "type": "string" }, "minimum_purchase_amount": { "type": "string" }, "price_per_unit": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "can_request", "purchased_units", "required_units", "currency", "minimum_purchase_amount", "price_per_unit", "reason" ] }, "countries": { "type": "array", "description": "Only countries with a verified SMS route. Requesting for anything\nelse is refused, exactly as it is on the web.", "items": { "type": "object", "additionalProperties": {} } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "is_required": { "type": "boolean" }, "accepted_formats": { "type": "array", "prefixItems": [ { "type": "string", "const": "pdf" }, { "type": "string", "const": "jpg" }, { "type": "string", "const": "jpeg" }, { "type": "string", "const": "png" } ], "minItems": 4, "maxItems": 4, "additionalItems": false }, "max_size_kb": { "type": "integer", "const": 5120 } }, "required": [ "uid", "name", "is_required", "accepted_formats", "max_size_kb" ] } }, "purposes": { "type": "array", "prefixItems": [ { "type": "string", "const": "Notification" }, { "type": "string", "const": "Transactional" }, { "type": "string", "const": "OTP \/ Verification" }, { "type": "string", "const": "Promotional" }, { "type": "string", "const": "Marketing" }, { "type": "string", "const": "Alerts & Reminders" }, { "type": "string", "const": "Other" } ], "minItems": 7, "maxItems": 7, "additionalItems": false }, "sender_id_rules": { "type": "object", "properties": { "min_length": { "type": "integer", "const": 3 }, "max_length": { "type": "integer", "const": 11 }, "pattern": { "type": "string", "const": "^[A-Za-z0-9]+( [A-Za-z0-9]+)*$" }, "description": { "type": "string", "const": "Letters, numbers, and single spaces between words. No symbols or accents. Outer whitespace is trimmed, repeated spaces are collapsed, and the sender ID is stored in uppercase." }, "reserved_names": { "type": "array", "prefixItems": [ { "type": "string", "const": "ADMIN" }, { "type": "string", "const": "ALERT" }, { "type": "string", "const": "BANK" }, { "type": "string", "const": "BANKING" }, { "type": "string", "const": "GOV" }, { "type": "string", "const": "GOVT" }, { "type": "string", "const": "INFO" }, { "type": "string", "const": "LOGIN" }, { "type": "string", "const": "NOTICE" }, { "type": "string", "const": "OTP" }, { "type": "string", "const": "PASSWORD" }, { "type": "string", "const": "SECURE" }, { "type": "string", "const": "SECURITY" }, { "type": "string", "const": "SERVICE" }, { "type": "string", "const": "SUPPORT" }, { "type": "string", "const": "SYSTEM" }, { "type": "string", "const": "TAX" }, { "type": "string", "const": "UNKNOWN" }, { "type": "string", "const": "UNVERIFIED" }, { "type": "string", "const": "VERIFY" }, { "type": "string", "const": "WHATSAPP" } ], "minItems": 21, "maxItems": 21, "additionalItems": false } }, "required": [ "min_length", "max_length", "pattern", "description", "reserved_names" ] }, "sample_message_rules": { "type": "object", "properties": { "min_length": { "type": "integer", "const": 50 }, "max_length": { "type": "integer", "const": 500 }, "description": { "type": "string", "const": "A real example of the messages you will send with this sender ID. Reviewers read it." } }, "required": [ "min_length", "max_length", "description" ] } }, "required": [ "eligibility", "countries", "documents", "purposes", "sender_id_rules", "sample_message_rules" ] } }, "required": [ "success", "request_uid", "data" ] } } } } } } }, "\/sms\/sender-ids\/requirements": { "get": { "operationId": "sms.sender-ids.requirements", "description": "Call this **before** requesting a sender ID. It returns everything that decides whether a request will be accepted, and those rules differ per platform and per account.\n\n- `eligibility.can_request` \u2014 `false` means the account has not bought enough SMS credits yet. `required_units` and `minimum_purchase_amount` say how much is needed. Do not attempt the request.\n- `countries[]` \u2014 the only countries this account may request for. A country appears here once a phone number has been verified for it under SMS Routes, because a sender ID is registered per country.\n- `documents[]` \u2014 every entry with `is_required: true` must be attached when you request. Use its `uid`.\n- `sender_id_rules` \u2014 3 to 11 characters of letters, numbers and single spaces between words, and a list of reserved words that are always refused. Case is yours to choose and is carried through to the handset.\n- `purposes` \u2014 the allowed purpose values; send exactly one as `purpose`.\n- `sample_message_rules` \u2014 50 to 500 characters.", "summary": "Get sender ID requirements", "tags": [ "Sender IDs" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "request_uid": { "type": "string" }, "data": { "type": "object", "properties": { "eligibility": { "type": "object", "properties": { "can_request": { "type": "boolean" }, "purchased_units": { "type": "integer" }, "required_units": { "type": "integer" }, "currency": { "type": "string" }, "minimum_purchase_amount": { "type": "string" }, "price_per_unit": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "can_request", "purchased_units", "required_units", "currency", "minimum_purchase_amount", "price_per_unit", "reason" ] }, "countries": { "type": "array", "description": "Only countries with a verified SMS route. Requesting for anything\nelse is refused, exactly as it is on the web.", "items": { "type": "object", "additionalProperties": {} } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "is_required": { "type": "boolean" }, "accepted_formats": { "type": "array", "prefixItems": [ { "type": "string", "const": "pdf" }, { "type": "string", "const": "jpg" }, { "type": "string", "const": "jpeg" }, { "type": "string", "const": "png" } ], "minItems": 4, "maxItems": 4, "additionalItems": false }, "max_size_kb": { "type": "integer", "const": 5120 } }, "required": [ "uid", "name", "is_required", "accepted_formats", "max_size_kb" ] } }, "purposes": { "type": "array", "prefixItems": [ { "type": "string", "const": "Notification" }, { "type": "string", "const": "Transactional" }, { "type": "string", "const": "OTP \/ Verification" }, { "type": "string", "const": "Promotional" }, { "type": "string", "const": "Marketing" }, { "type": "string", "const": "Alerts & Reminders" }, { "type": "string", "const": "Other" } ], "minItems": 7, "maxItems": 7, "additionalItems": false }, "sender_id_rules": { "type": "object", "properties": { "min_length": { "type": "integer", "const": 3 }, "max_length": { "type": "integer", "const": 11 }, "pattern": { "type": "string", "const": "^[A-Za-z0-9]+( [A-Za-z0-9]+)*$" }, "description": { "type": "string", "const": "Letters, numbers, and single spaces between words. No symbols or accents. Outer whitespace is trimmed, repeated spaces are collapsed, and the sender ID is stored in uppercase." }, "reserved_names": { "type": "array", "prefixItems": [ { "type": "string", "const": "ADMIN" }, { "type": "string", "const": "ALERT" }, { "type": "string", "const": "BANK" }, { "type": "string", "const": "BANKING" }, { "type": "string", "const": "GOV" }, { "type": "string", "const": "GOVT" }, { "type": "string", "const": "INFO" }, { "type": "string", "const": "LOGIN" }, { "type": "string", "const": "NOTICE" }, { "type": "string", "const": "OTP" }, { "type": "string", "const": "PASSWORD" }, { "type": "string", "const": "SECURE" }, { "type": "string", "const": "SECURITY" }, { "type": "string", "const": "SERVICE" }, { "type": "string", "const": "SUPPORT" }, { "type": "string", "const": "SYSTEM" }, { "type": "string", "const": "TAX" }, { "type": "string", "const": "UNKNOWN" }, { "type": "string", "const": "UNVERIFIED" }, { "type": "string", "const": "VERIFY" }, { "type": "string", "const": "WHATSAPP" } ], "minItems": 21, "maxItems": 21, "additionalItems": false } }, "required": [ "min_length", "max_length", "pattern", "description", "reserved_names" ] }, "sample_message_rules": { "type": "object", "properties": { "min_length": { "type": "integer", "const": 50 }, "max_length": { "type": "integer", "const": 500 }, "description": { "type": "string", "const": "A real example of the messages you will send with this sender ID. Reviewers read it." } }, "required": [ "min_length", "max_length", "description" ] } }, "required": [ "eligibility", "countries", "documents", "purposes", "sender_id_rules", "sample_message_rules" ] } }, "required": [ "success", "request_uid", "data" ] } } } } } } } }, "components": { "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }