Overview

The SMS API is a microservice version of our SMS gateway. It sends a text message using the configured gateways in a prioritized order.

Limitations

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

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, please refer to Accessing Signicat REST services. When retrieving the token, the scope client.sms.send must be specified.

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, you will need to contact Signicat Support to have the necessary configurations enabled on our side.

API

Environment
Base URL
Beta https://beta.signicat.com
Preproduction https://preprod.signicat.com
Production https://id.signicat.com
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 probably 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

JSON Request

{
    "sender": "+4740003410",
    "recipient": "+4798765432",
    "message": "Hi! This is your one-time code for authentication: 1234"
}