Integration guide

1. Authentication

Call from your server with api-key and Content-Type: application/json headers.

2. Understand params and placeholders

${code} reserves a place in your template. params.code supplies the value for this message:

Your code is ${code}, valid for 5 minutes.

{ "params": { "code": "008848" } }

Use code as the key, not ${code}, and match the placeholder’s case. Values must be digits-only strings, such as "008848". Omit params if there are no placeholders.

3. Send an SMS

Copy and customize this example

This example uses France’s calling code, 33. Replace the API key, approved template ID and recipient with your own test number, and confirm the destination is available.

curl -X POST 'https://api.starsg.ai/api/product/sms/send' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "SMS_0123456789",
    "countryCode": "33",
    "phone": "612345678",
    "params": { "code": "008848" }
  }'

Send a JSON object directly: no body wrapper or extra /v1. This example uses a template containing ${code}.

4. Check the result

Check success first. Save messageId (channel message ID) and resultId (send record ID) on success; inspect errorCode/errorMsg on failure. Sending success does not confirm receipt on the phone.

{
  "success": true,
  "data": {
    "messageId": "channel-message-id",
    "resultId": 9
  },
  "errorCode": null,
  "errorMsg": null
}

{
  "success": false,
  "data": null,
  "errorCode": "END_USER_TEMPLATE_NOT_APPROVED",
  "errorMsg": "Template is awaiting review"
}

Common errors and next steps

Supported countries and regions

Check destination availability before sending. Destinations requiring SID registration are coming soon. Enter the calling code below in countryCode without +, and enter the phone number separately in phone.