SMS Shared Service API

The SMS Shared Service allows product backends to dispatch transactional SMS messages without directly integrating with telecommunication providers. Teams provide the message content in each request; APICenter does not store SMS templates.

For a Node.js backend, the typed client is api.sms.send(...) in the APICenter SDK. The REST reference below documents the same API for other runtimes.

Service Specifications

• Base Route: /api/v1/shared/sms
• Required Header: Authorization: Bearer <SERVICE_ACCESS_TOKEN>
• Required Header: Idempotency-Key: <16–255 characters>

1. Send Single SMS

• Endpoint: POST /api/v1/shared/sms/send

Request Body (SmsSendRequest)

{
  "to": "+639171234567",
  "message": "Your order #ORDER-991204 has been dispatched!",
  "senderId": "APICENTER"
}

Response (SmsSendResponse) — 201 Created

{
  "success": true,
  "data": {
    "messageId": "msg_9918231a48f29d10a9f",
    "status": "sent",
    "to": "+639171234567",
    "sentAt": "2026-07-31T23:20:00.000Z",
    "recipient": "+639171234567"
  }
}

Retries with the same key and request body replay the original status and response for seven days. Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. If delivery has an uncertain outcome, APICenter blocks the key for reconciliation instead of sending again.

2. Get SMS Message Status

• Endpoint: GET /api/v1/shared/sms/status/:messageId

Response — 200 OK

{
  "success": true,
  "data": {
    "messageId": "msg_9918231a48f29d10a9f",
    "to": "+639171234567",
    "message": "Your order #ORDER-991204 has been dispatched!",
    "status": "sent",
    "createdAt": "2026-07-31T23:20:00.000Z"
  }
}

Requests containing the obsolete templateId field return 400. Send the message content in message instead.