Send SMS

Endpoint Overview

POST /api/v1/sms/send-sms

Description

This endpoint enables you to send an SMS to a specified mobile number using a pre-approved DLT template. The service accepts a template ID, sender ID, recipient mobile number, and template variables, sends the SMS via Surepass infrastructure, and returns a client_id that can be used to track the message.

This API is suitable for transactional alerts, customer notifications, and other DLT-compliant SMS use cases.

Key Benefits

Supports a wide range of SMS use cases, including alerts, notifications, and transactional messages

Ensures DLT compliance by using registered templates and sender IDs

Simplifies integration with a consistent request/response structure

Use Cases

Financial Services

E-commerce

Healthcare

Transaction and balance alerts

Payment confirmations and EMI reminders

Account activity notifications

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Base URL for this API:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
template_id	String	Yes	The SMS template ID registered with telecom/DLT authorities
sender_id	String	Yes	The Sender ID (Header) registered on DLT for this template
mobile	String	Yes	The mobile number to which the SMS will be sent (10-digit format without country code)
variables	Object	No	Key-value map for template variables (e.g. `var1`, `var2`, ...), depending on your template

Example Request

{
    "template_id": "1707181302450588811",
    "sender_id": "TEST",
    "mobile": "9999999999",
    "variables": {
        "var1": "9978",
        "var2": "9978"
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.client_id	String	Unique identifier for this SMS request, useful for tracking
data.created_at	String	Timestamp when the SMS request was created
data.sender_id	String	Sender ID used for this SMS
data.template_id	String	Template ID used for this SMS
data.mobile	String	The mobile number to which the SMS was sent
data.status	String	Current status of the SMS (e.g. `sent`)
data.message	String	Final message text sent to the user (after variable substitution)
data.error_code	String?	Provider or internal error code, if any
data.error_message	String?	Human-readable error message from provider, if any
status_code	Integer	HTTP-like status code of the response
success	Boolean	Indicates if the API call was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code representing the result

Example Successful Response

{
    "data": {
        "client_id": "send_sms_lhPuyQfweToMjivctmnZ",
        "created_at": "2025-12-22T11:47:44.990884",
        "sender_id": "TEST",
        "template_id": "1707181302450588811",
        "mobile": "9999999999",
        "status": "sent",
        "message": "Your transaction of INR 1,000 has been processed successfully. Thank you for using Test Technologies.",
        "error_code": null,
        "error_message": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Template ID

Server Error

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Invalid Template ID or Sender ID provided.",
    "message_code": null
}

The template ID provided doesn't exist or is not approved for use.

Integration Best Practices

Security Recommendations

Store the client_id securely so you can track and troubleshoot SMS deliveries.

Protect your API keys and JWT tokens; never expose them in client-side code.

Avoid logging sensitive personal data from SMS content or variables in plaintext.

Implement input validation on your side for mobile and variables before calling the API.

User Experience Guidelines

Clearly inform users when they will receive SMS notifications (e.g. for orders, alerts, or reminders)

Keep SMS content concise and aligned with the approved DLT template

For marketing or promotional SMS, provide clear opt-out instructions where required by regulation

Ensure sending times respect user time zones and local regulations (e.g. no late-night promotional SMS where restricted)

Related APIs

SMS OTP APIs: Generate, send, and verify one-time passwords (OTPs) via SMS for a given mobile number.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/sms/send-sms' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "template_id": "1707181302450588811", "sender_id": "TEST", "mobile": "9999999999", "variables": { "var1": "9978", "var2": "9978" } }'

{ "data": { "client_id": "send_sms_lhPuyQfweToMjivctmnZ", "created_at": "2025-12-22T11:47:44.990884", "sender_id": "TEST", "template_id": "1707181302450588811", "mobile": "9999999999", "status": "sent", "message": "#One Time Password is 123456. This is usable once and expire in 10 minutes. Please do not share this with anyone. - Test Technologies", "error_code": null, "error_message": null }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Send SMS

Send SMS#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Request

Responses

Send SMS

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices