Skip to main content
Version: 2.1.38

Sms Channel Service API Specification

This page describes how to integrate with the SMS Channel Service on a technical level.

This service is a specialized downstream service, typically called by the central Notification Service. Its sole responsibility is to handle the formatting and dispatching of SMS notifications.

REST Resources​

The SMS Channel Service provides a single resource for sending an SMS notification.

The SMS Notification Resource​

An SMS notification request defines the content to be sent to a user's mobile device. It consists of:

  • reference: A unique ID for tracking this specific send request.
  • sender: The sender ID, which can be a brand name (e.g., "Banqup") or a short code.
  • phoneNumber: The recipient's mobile number, preferably in E.164 format.
  • message: The text content of the SMS.

An example of an SMS notification request in JSON format:

{
  "reference": "tx_12345_abc",
  "sender": "Banqup",
  "phoneNumber": "+447123456789",
  "message": "Your verification code is 54321."
}

When this SMS is successfully queued for sending, the service returns a unique notificationId:

{
  "notificationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Sending an SMS​

To send a new SMS, you'll perform a POST request to the **/core/sms/v1/smses ** endpoint, providing the full SMS notification object in the request body.

POST /v1/notifications/sms
Content-Type: application/json

{
  "reference": "tx_12345_abc",
  "sender": "Banqup",
  "phoneNumber": "+447123456789",
  "message": "Your verification code is 54321."
}

A successful response (HTTP 202 Accepted) will return the notificationId confirming the SMS has been accepted for delivery.

Security​

Access to send SMS messages is controlled by the sms_send security scope. All requests to the SMS Channel API must be authenticated using an OAuth security scheme and include a token with the required scope.

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.

OAuth Flow (authorizationCode):

Scopes:

  • info: Scopes are endpoint-specific, see each endpoint for required scope.