ShoutOUT API

Developer Guides

Use these API examples to send SMS messages and add one-time password verification to your application.

Authentication

Include your API key in the Authorization header of every request. Keep the key on your server and never expose it in browser or mobile client code.

Authorization: Apikey YOUR_API_KEY

All requests in this guide send JSON, so include Content-Type: application/json.

POST https://backgroundservice.getshoutout.com/v1/messages

Send an SMS

Send the same message to one or more mobile numbers. Use international-format numbers without a leading +.

Field	Type	Description
`source`	string	Your approved sender ID.
`destinations`	string[]	One or more recipient mobile numbers.
`content.sms`	string	The SMS message text.
`transports`	string[]	Use `["sms"]` for SMS delivery.
`priority`	number	Sets the message delivery priority. The current example uses `0`.

curl -X POST https://backgroundservice.getshoutout.com/v1/messages \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "ShoutDEMO",
    "destinations": ["94777123456"],
    "content": {
      "sms": "Hello from ShoutOUT API"
    },
    "transports": ["sms"],
    "priority": 0
  }'

POST https://backgroundservice.getshoutout.com/v1/messages

Send a priority SMS

Priority SMS uses the same message endpoint. Include the priority field in the request body; the current priority SMS example uses 0.

curl -X POST https://backgroundservice.getshoutout.com/v1/messages \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "ShoutDEMO",
    "destinations": ["94777123456"],
    "content": {
      "sms": "Hello from ShoutOUT API"
    },
    "transports": ["sms"],
    "priority": 0
  }'

POST https://backgroundservice.getshoutout.com/otpservice/send

Send an OTP

Send a one-time password to a recipient. Include {{code}} in the message text; ShoutOUT replaces it with the generated verification code.

Field	Type	Description
`source`	string	Your approved sender ID.
`destination`	string	The recipient mobile number.
`content.sms`	string	The OTP message template containing `{{code}}`.
`transport`	string	Use `"sms"` for SMS delivery.

curl -X POST https://backgroundservice.getshoutout.com/otpservice/send \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "ShoutDEMO",
    "destination": "94777123456",
    "content": {
      "sms": "Your verification code is {{code}}"
    },
    "transport": "sms"
  }'

Keep the referenceId returned by the send request. You need it to verify the code submitted by the recipient.

POST https://backgroundservice.getshoutout.com/otpservice/verify

Verify an OTP

Submit the code entered by the recipient together with the referenceId from the send request.

Field	Type	Description
`code`	string	The verification code entered by the recipient.
`referenceId`	string	The reference returned when the OTP was sent.

curl -X POST https://backgroundservice.getshoutout.com/otpservice/verify \
  -H "Authorization: Apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "12345",
    "referenceId": "2d313c9a-6c6e-4c64-b9ad-2d4e0e3d9f7b"
  }'