SMS API

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

Base URL: https://api.wayscloud.services

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:

json

{
  "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:

bash

curl -X POST https://api.wayscloud.services/v1/sms/send \
  -H "X-API-Key: wayscloud_sms_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "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:

json

{
  "sms_message_id": "550e8400-e29b-41d4-a716-446655440000",
  "to": [
    "+4799999999"
  ],
  "status": "QUEUED",
  "units_estimate": 1,
  "customer_ref": "order-12345"
}

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:

bash

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

Response:

json

{
  "messages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "direction": "OUTBOUND",
      "to_number": "+4799999999",
      "body": "Your order #1234 has shipped.",
      "status": "DELIVERED",
      "units_count": 1,
      "created_at": "2026-03-30T10:00:00Z"
    },
    {
      "id": "660f9511-f3a0-5483-b827-1f13c4d55111",
      "direction": "OUTBOUND",
      "to_number": "+4798765432",
      "body": "Meeting at 14:00 today.",
      "status": "SENT",
      "units_count": 1,
      "created_at": "2026-03-30T09:30:00Z"
    }
  ],
  "total": 47,
  "page": 1,
  "page_size": 50,
  "has_more": false
}

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:

bash

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

Response:

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "OUTBOUND",
  "message_type": "PLAIN",
  "from_number": null,
  "to_number": "+4799999999",
  "body": "Your order #1234 has shipped.",
  "status": "DELIVERED",
  "units_count": 1,
  "customer_ref": "order-1234",
  "created_at": "2026-03-30T10:00:00Z",
  "sent_at": "2026-03-30T10:00:01Z",
  "delivered_at": "2026-03-30T10:00:03Z",
  "error_message": null
}

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:

bash

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

Response:

json

{
  "message": "Message cancelled",
  "message_id": "550e8400-e29b-41d4-a716-446655440000"
}

GET /v1/sms/sender-profiles

List sender profiles

List your configured sender profiles (sender IDs).

Response example:

json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "marketing",
    "sender_id": "MyBrand",
    "is_default": false,
    "allow_reply": false,
    "is_custom_sender": true,
    "approval_status": "approved",
    "monthly_price": 99.0,
    "created_at": "2025-01-15T10:00:00Z"
  }
]

Example:

bash

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

Response:

json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "marketing",
    "sender_id": "MyBrand",
    "is_default": false,
    "allow_reply": false,
    "is_custom_sender": true,
    "approval_status": "approved",
    "monthly_price": 99.0,
    "created_at": "2025-01-15T10:00:00Z"
  }
]

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:

json

{
  "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:

bash

curl -X POST https://api.wayscloud.services/v1/sms/sender-profiles \
  -H "X-API-Key: wayscloud_sms_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "marketing",
  "sender_id": "MyBrand",
  "allow_reply": false,
  "brand_confirmation": true
}'

Response:

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "marketing",
  "sender_id": "MyBrand",
  "is_default": false,
  "allow_reply": false,
  "is_custom_sender": true,
  "approval_status": "approved",
  "monthly_price": 99.0,
  "created_at": "2025-01-15T10:00:00Z"
}

DELETE /v1/sms/sender-profiles/

Delete sender profile

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

Example:

bash

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

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:

bash

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

Response:

json

{
  "active": true,
  "has_sender_profiles": true,
  "has_api_key": true,
  "default_sender": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "default",
    "sender_id": "4799999999",
    "is_default": true
  },
  "messages_today": 12,
  "messages_this_month": 347,
  "messages_sent_30d": 892,
  "messages_received_30d": 45
}

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:

bash

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

Response:

json

{
  "period": "2025-12",
  "period_start": "2025-12-01",
  "period_end": "2025-12-31",
  "messages_sent": 150,
  "messages_received": 23,
  "messages_failed": 2,
  "units_used": 167,
  "cost": 165.33,
  "currency": "NOK",
  "price_per_unit": 0.99,
  "outbound_cost": 165.33,
  "inbound_cost": 0.0
}

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:

bash

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

Response:

json

{
  "today": {
    "messages_sent": 12,
    "messages_received": 3,
    "units_used": 14,
    "delivery_rate": 0.92
  },
  "this_week": {
    "messages_sent": 45,
    "messages_received": 8,
    "units_used": 52,
    "delivery_rate": 0.95
  },
  "this_month": {
    "messages_sent": 150,
    "messages_received": 23,
    "units_used": 167,
    "delivery_rate": 0.98
  },
  "last_30_days": {
    "messages_sent": 180,
    "messages_received": 28,
    "units_used": 201,
    "delivery_rate": 0.97
  },
  "status_breakdown": {
    "QUEUED": 5,
    "SENT": 10,
    "DELIVERED": 130,
    "FAILED": 5
  }
}

SMS API ​

Endpoints ​

POST /v1/sms/send ​

GET /v1/sms/messages ​

GET /v1/sms/messages/ ​

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

GET /v1/sms/sender-profiles ​

POST /v1/sms/sender-profiles ​

DELETE /v1/sms/sender-profiles/ ​

GET /v1/sms/status ​

GET /v1/sms/usage ​

GET /v1/sms/stats ​

Related ​

SMS API

Endpoints

POST /v1/sms/send

GET /v1/sms/messages

GET /v1/sms/messages/

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

GET /v1/sms/sender-profiles

POST /v1/sms/sender-profiles

DELETE /v1/sms/sender-profiles/

GET /v1/sms/status

GET /v1/sms/usage

GET /v1/sms/stats

Related