link

# SMS API

# Introduction

The SMS API is a microservice version of Signicat's SMS gateway. It can be used to send a text message using the configured gateways in a prioritised order.

# Limitations

The current version of the SMS API has the following limitations:

  • The SMS API may only be used for sending one-time passwords.
  • Only one text message with one recipient may be sent in each call.
  • Message length:
    • Containing characters that can be 7-bit encoded. Max: 160 characters
    • Containing characters that must be UCS-2 encoded. Max: 70 symbols
  • A positive response from the SMS API does not guarantee that the message has been sent to the recipient. It means that the text message was accepted by one of the configured SMS gateways and that this gateway will try to deliver the message to the recipient.

# Using the service

# Authentication

All requests must be authenticated by means of an OIDC access token, supplied as an Authorization header of type Bearer. For more instructions on how to obtain such a token, see Accessing Signicat REST Services. When retrieving the token, the scope client.sms.send must be specified.

Important

Failing to specify the client.sms.send scope when requesting the OIDC access token will cause the SMS API microservice to respond with an HTTP Client Error.

If you specify the scope correctly, but you are not able to get a valid OIDC access token, contact us at support@signicat.com so we can enable the necessary configurations on our side.

# API

Environment Base URL
Beta https://beta.signicat.com (opens new window)
Pre-production https://preprod.signicat.com (opens new window)
Production https://id.signicat.com (opens new window)
Path Verb Content type Input Output
/sms/messages POST application/json Sms HTTP Response Code

# Messages/ objects

# Requests

The request body must contain an Sms object in the JSON format.

# Responses

The service will either respond with HTTP Response code 200 if the operation was successful, or an error code if it failed. See Understanding results for more details.

# Objects composing requests/ responses

# Sms

Name Type Description
sender String The sender of the text message. This field must either be numeric and consist of up to 15 digits ([0-9]), or be alphanumeric and consist of 1 to 11 characters in the range [A-Za-z0-9 ].
recipient String The recipient of the text message. Must be a valid E.164 phone number with a maximum of fifteen digits and be formatted as follows: [+][country code][subscriber number including area code]
message String The text that should be delivered in the text message. Must be a string with at least one character.

# Understanding results

# HTTP response code 200

An empty response with HTTP response code 200 indicates that the SMS API was successful in delegating the SMS sending to one of the configured gateways. Note that this does not guarantee that the message will be delivered to the recipient.

# HTTP response code 400

The request sent by the HTTP client was invalid. In this case the response body will provide more information. Below is an example of what the response will look like when the message property is missing in the request.

# JSON error response

{
    "instance":"https://id.signicat.com/sms/messages",
    "method":"POST",
    "status":400,
    "type":"base:constraint-violation-problem",
    "title":"400 Bad Request",
    "violations":[{"message":"The sms property 'message' has to be set"}]
}

# HTTP response code 500

A server error occurred on our side. We are sorry for the inconvenience. We will most likely have detected the problem and will be working on fixing it, but do not hesitate to contact us and file a ticket.

The SMS API failed to delegate the SMS sending to any of the configured gateways. This may be due to a configuration error, network communications error or a problem in the SMS payload causing it to be rejected by all the gateways.

# Sample request

{
    "sender": "+4740003410",
    "recipient": "+4798765432",
    "message": "Hi! This is your one-time code for authentication: 1234"
}
Last updated: 08/10/2021 13:20 UTC