SMS Notifications

Send SMS messages to users for one-time passwords, alerts, notifications, and campaigns via the Ping API.

The SMS model

The SMS notification model contains all the information about SMS messages sent through the Ping platform.

Properties

Name
public_id
Type
string
Description
Unique identifier for the SMS notification.
Name
to_phone
Type
string
Description
Recipient phone number in E.164 international format (e.g., +263771234567).
Name
message
Type
string
Description
SMS message content. Maximum 160 characters for a single SMS segment.
Name
sender_id
Type
string
Description
Custom sender ID for the SMS. Must be approved in your dashboard before use.
Name
provider
Type
string
Description
SMS provider used to send the message (auto-selected if not specified).
Name
status
Type
string
Description
Delivery status: success, failed, pending.
Name
message_id
Type
string
Description
External provider message ID for tracking delivery status.
Name
created_at
Type
timestamp
Description
Timestamp of when the SMS was created.

POST/v1/notification/api/sms/send

Send SMS

Send an SMS message to one or multiple recipients. Supports single phone numbers, arrays of phone numbers, or recipient groups.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with sms permission.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
to_phone
Type
string | array
Description
Recipient phone number or array of phone numbers in E.164 format (e.g., "+263771234567"). Alternatively, provide recipient_group_id.
Name
message
Type
string
Description
SMS message content to send.

Optional attributes

Name
recipient_group_id
Type
string
Description
Send to all members of a recipient group instead of individual phone numbers.
Name
sender_id
Type
string
Description
Custom sender ID (must be approved). If omitted, uses your default approved sender ID.
Name
provider
Type
string
Description
Specific SMS provider to use. Options: econet, netone, telecel, twilio. Auto-selected if not specified.
Name
scheduled_time
Type
string
Description
Schedule the SMS for future delivery in format: YYYY-MM-DD HH:MM:SS.
Name
time_zone
Type
string
Description
Timezone for scheduled_time (default: Africa/Harare).

Request

POST

/v1/notification/api/sms/send

curl -X POST https://api.ping.co.zw/v1/notification/api/sms/send \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "message": "Your OTP is 123456. Valid for 10 minutes."
  }'

Response

{
  "result": "success",
  "message": "SMS sent successfully",
  "billing": {
    "cost": 0.05,
    "currency": "USD",
    "provider": "econet"
  },
  "details": {
    "status": "success",
    "message_sid": "SM1234567890abcdef"
  }
}

POST/v1/notification/sms/send/:template_name

Send SMS with template

Send an SMS using a pre-configured template. Templates support variable substitution for personalized messages.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key with sms and templates permissions.
Name
Content-Type
Type
string
Description
Must be application/json.

Required attributes

Name
to_phone
Type
string | array
Description
Recipient phone number(s) in E.164 format.
Name
template_data
Type
object
Description
Variables to substitute in the template (e.g., {"otp": "123456", "expiry_minutes": "10"}).

Optional attributes

Name
sender_id
Type
string
Description
Custom sender ID (must be approved).
Name
provider
Type
string
Description
Specific SMS provider to use.

Request

POST

/v1/notification/sms/send/otp_verification

curl -X POST https://api.ping.co.zw/v1/notification/sms/send/otp_verification \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone": "+263771234567",
    "template_data": {
      "otp": "482910",
      "expiry_minutes": "10"
    }
  }'

Response

{
  "result": "success",
  "message": "SMS sent successfully using template",
  "template_used": "otp_verification",
  "processed_message": "Your OTP is 482910. Valid for 10 minutes.",
  "billing": {
    "cost": 0.05,
    "currency": "USD",
    "provider": "econet"
  },
  "details": {
    "status": "success",
    "message_sid": "SM1234567890abcdef"
  }
}

GET/v1/notification/api/history/sms

List SMS history

Retrieve a paginated list of SMS notifications sent through your account.

Required headers

Name
X-Ping-Api-Key
Type
string
Description
Your API key.

Optional parameters

Name
skip
Type
integer
Description
Number of records to skip (default: 0).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 50, max: 100).

Request

GET

/v1/notification/api/history/sms

curl -G https://api.ping.co.zw/v1/notification/api/history/sms \
  -H "X-Ping-Api-Key: pk_live_your_api_key" \
  -d limit=10 \
  -d skip=0

Response

{
  "result": "success",
  "notifications": [
    {
      "public_id": "sms_abc123def456",
      "recipient": "+263771234567",
      "message": "Your OTP is 123456. Valid for 10 minutes.",
      "sender": "YourApp",
      "provider": "econet",
      "status": "success",
      "message_id": "SM1234567890abcdef",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}