SMS API

Send SMS messages and manage inbound keywords. Pay-as-you-go pricing.

Endpoints

Method	Path	Description
POST	/v1/sms/send	Send SMS
GET	/v1/sms/messages	List messages
GET	/v1/sms/messages/{message_id}	Get message
POST	/v1/sms/messages/{message_id}/cancel	Cancel scheduled message
GET	/v1/sms/sender-profiles	List sender profiles
POST	/v1/sms/sender-profiles	Create sender profile
DELETE	/v1/sms/sender-profiles/{profile_id}	Delete sender profile
GET	/v1/sms/status	Get service status
GET	/v1/sms/usage	Get SMS usage for billing
GET	/v1/sms/stats	Get SMS statistics

POST /v1/sms/send

Send SMS

Send SMS message(s) to one or more recipients.

Recipients: Specify at least one of:

• to: List of phone numbers (E.164 format, e.g., +4799999999)
• to_contacts: List of contact UUIDs from your contact directory
• to_groups: List of contact group UUIDs

Message Length:

• GSM-7 (standard): 160 chars = 1 SMS, then 153 chars per part
• Unicode (emoji, etc.): 70 chars = 1 SMS, then 67 chars per part
• Max 1600 chars (10 parts)

Scheduling:

• Use scheduled_at for future delivery (ISO 8601 format, max 30 days ahead)
• By default, scheduled_at is interpreted as UTC
• Use timezone parameter to specify local time (IANA format, e.g., "Europe/Oslo")
• Scheduled messages can be cancelled using POST /messages/{id}/cancel

Delivery Reports: Provide callback_url (HTTPS) to receive status webhooks.

Request Body:

Field	Type	Description
to	array	List of recipient phone numbers (E.164 format)
to_contacts	array	List of contact UUIDs to send to
to_groups	array	List of contact group UUIDs to send to
message	string	Required. Message content
sender_profile_id	string	Sender profile ID (uses default if not specified)
allow_reply	boolean	Allow recipient to reply
customer_ref	string	Your reference ID for correlation
callback_url	string	Webhook URL for delivery status (HTTPS required)
scheduled_at	string	Schedule for future delivery (ISO 8601). Max 30 days ahead. Use timezone param for local time.
timezone	string	IANA timezone for scheduled_at (e.g., Europe/Oslo, Europe/Stockholm). If omitted, scheduled_at is treated as UTC.

Example:

{
  "to": [
    "+4799999999"
  ],
  "message": "Reminder: Your appointment is tomorrow at 10:00",
  "scheduled_at": "2025-12-17T09:00:00",
  "timezone": "Europe/Oslo",
  "customer_ref": "reminder-12345"
}

Response:

Field	Type	Description
sms_message_id	string	Unique message ID
to	array	Recipient numbers
status	string	Message status Values: QUEUED, SCHEDULED, SENDING, SENT, DELIVERED, FAILED
scheduled_at	string
units_estimate	integer	Estimated SMS units
customer_ref	string

Example:

curl -X POST https://api.wayscloud.services/v1/sms/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/sms/messages

List messages

List sent and received SMS messages with optional filters.

Response:

Field	Type	Description
messages	array
total	integer
page	integer
page_size	integer
has_more	boolean

Example:

curl https://api.wayscloud.services/v1/sms/messages \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/sms/messages/

Get message

Get details for a specific SMS message.

Response:

Field	Type	Description
id	string
direction	string	Values: OUTBOUND, INBOUND
message_type	string	Values: PLAIN, REPLY, VERIFY
from_number	string
to_number	string
body	string
status	string	Values: QUEUED, SCHEDULED, SENDING, SENT, DELIVERED, FAILED, CANCELLED, RECEIVED
units_count	integer
customer_ref	string
created_at	string
scheduled_at	string
sent_at	string
delivered_at	string
related_message_id	string
error_message	string

Example:

curl https://api.wayscloud.services/v1/sms/messages/{message_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/sms/messages/{message_id}/cancel

Cancel scheduled message

Cancel a scheduled or queued SMS message before it is sent.

Cancellable statuses:

• SCHEDULED - Message waiting for scheduled time
• QUEUED - Message in send queue

Messages that are already SENDING, SENT, DELIVERED, or FAILED cannot be cancelled.

Response:

Field	Type	Description
message	string
message_id	string

Example:

curl -X POST https://api.wayscloud.services/v1/sms/messages/{message_id}/cancel \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/sms/sender-profiles

List sender profiles

List your configured sender profiles (sender IDs).

Response:

Example:

curl https://api.wayscloud.services/v1/sms/sender-profiles \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/sms/sender-profiles

Create sender profile

Create a new sender profile (sender ID).

Sender ID Types:

• Phone number: Your own number or a dedicated number
• Alphanumeric: Brand name (max 11 chars, no ÆØÅ, requires brand_confirmation)

Custom alphanumeric sender IDs require admin approval and may have a monthly fee.

Request Body:

Field	Type	Description
name	string	Required. Profile name
sender_id	string	Required. Sender ID (phone or alphanumeric max 11 chars, no ÆØÅ)
allow_reply	boolean
is_default	boolean
brand_confirmation	boolean	Required for custom sender IDs

Example:

{
  "name": "marketing",
  "sender_id": "MyBrand",
  "allow_reply": false,
  "brand_confirmation": true
}

Response:

Field	Type	Description
id	string
name	string
sender_id	string	Phone number or alphanumeric (max 11 chars)
is_default	boolean
allow_reply	boolean
is_custom_sender	boolean
approval_status	string	Values: pending, approved, rejected
monthly_price	number
created_at	string

Example:

curl -X POST https://api.wayscloud.services/v1/sms/sender-profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

DELETE /v1/sms/sender-profiles/

Delete sender profile

Delete a sender profile. Cannot delete the default profile if it is the only one.

Example:

curl -X DELETE https://api.wayscloud.services/v1/sms/sender-profiles/{profile_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/sms/status

Get service status

Get SMS service status including message counts and default sender.

Response:

Field	Type	Description
active	boolean
has_sender_profiles	boolean
has_api_key	boolean
default_sender	SenderProfile
messages_today	integer
messages_this_month	integer
messages_sent_30d	integer
messages_received_30d	integer

Example:

curl https://api.wayscloud.services/v1/sms/status \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/sms/usage

Get SMS usage for billing

Get SMS usage statistics for a billing period.

Returns message counts, SMS units consumed, and cost breakdown.

Pricing per SMS unit:

• NOK: 0.99
• SEK: 0.99
• DKK: 0.79
• EUR: 0.10
• USD: 0.10

Cost is calculated as: units_used × price_per_unit

Response:

Field	Type	Description
period	string	Billing period (YYYY-MM)
period_start	string
period_end	string
messages_sent	integer	Total outbound messages
messages_received	integer	Total inbound messages
messages_failed	integer	Failed messages
units_used	integer	SMS units consumed
cost	number	Total cost
currency	string	Currency code
price_per_unit	number	Price per SMS unit
outbound_cost	number	Cost for outbound messages
inbound_cost	number	Cost for inbound messages (usually 0)

Example:

curl https://api.wayscloud.services/v1/sms/usage \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/sms/stats

Get SMS statistics

Get aggregated SMS statistics across multiple time periods.

Returns message counts, units, and delivery rates for:

• Today
• This week
• This month
• Last 30 days

Also includes a breakdown by message status (QUEUED, SENT, DELIVERED, FAILED, etc).

Response:

Field	Type	Description
today	SMSStatsPeriod
this_week	SMSStatsPeriod
this_month	SMSStatsPeriod
last_30_days	SMSStatsPeriod
status_breakdown	object	Message count by status

Example:

curl https://api.wayscloud.services/v1/sms/stats \
  -H "X-API-Key: YOUR_API_KEY"

---