An API for sending SMS or One-time verification codes.

API Calls

Send SMS: POST to https://env.zignsec.com/v2/mmessaging

SMS status: GET from https://env.zignsec.com/v2/mmessaging/id {/code}

where env is API or test. The id is the message identifier from send call’s response. code is optional when OTP validation is performed.

Overview of Use Cases

The two methods in the SMS Messaging API:

  • Send an SMS. Optionally use the SMS for a mobile verification, also known as sending an OTP code (One Time Password) to verify the access to the mobile phone. Theses added parameters for OTP are described here.
  • Check the delivery status of a sent SMS. Optionally validate the OTP code simultaneously if that was the use case.

Note that this API has two use cases – for sending SMS and for OTP verification, ie sending and verifying one-time passwords, aka Two Factor Authentication (2FA). In the 2FA use case, we auto-generate in the message an OTP code for the end user to validate (OTP=One Time Password). If the SMS text contains the text {0} it means you want to run the OTP Login use case. The {0} text will be replaced with an auto-generated four-digit OTP code, and the delivery status end-point will be both be a validator of the correct OTP code, and reporter of the current SMS delivery status.

Common Response JSON for Send and Status

This Response is returned both after a Send and after a Status Check.

Step 1. Send an SMS

To send a SMS message, optionally for Otp verification.

API

POST to https://env.zignsec.com/v2/mmessaging    where env is api or test.

Request Header

In order to send a message you need to authenticate yourself using the credentials given by ZignSec.
AuthorizationSpecifies the ZignSec authorization that you get from ZignSec Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0Required
Content-TypeSpecifies the media type of the request body data. Set to application/x-www-form-urlencoded for post data and application/json for JSON object. Example: Content-Type: application/x-www-form-urlencodedRequired
HostUse test.zignsec.com for test environment and api.zignsec.com for production environment. Example: api.zignsec.comRequired

Request Body

This request contains:
ParameterDescriptionRequired
fromThis is the Sender. Numerical is max length of 16. Alphanumeric sender is limited to GSM default alphabet with max length of 11. This is also called the SenderID. Example: from=ZignSecYes.
toThe receiver´s phone number including country code, but not including a leading + or 00. Exampleto=46123456789Yes.
textThe SMS body. Messages where type is text (the default) are in UTF-8 with URL encoding. Contents of the message, URL encoded is necessary. Note: If the text contains the string {0} the use case 2FA-login is activated and the {0} is replaced with an auto-generated four digit OTP code. Message longer than 160 characters will automatically concatenate to up to 13 SMS with 153 characters each for a total length of 2000 characters. Each part in a concatenated message is credited as one SMS. You can see the full UTF-8 character set here: http://www.fileformat.info/info/charset/UTF-8/list.htm. To test if your message can be URL encoded, use: http://www.url-encode-decode.com/. Example: text=This+is+the+URL-encoded+messageYes

Example:

POST https://test.zignsec.com/v2/mmessaging HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/json
Host: test.zignsec.com
Content-Length: 71
{

"to":"46123456789",

"from":"ZignSec",

"text":"This+is+the+URL-encoded+message {0}",

"RelayState":"123456"

} 

OTP

OTP stands for One Time PIN and is used to carry out 2FA (Two Factor Authentication) with help of a phone number. ZignSec makes it easy to generate, implement and verify a OTP-code. If you want to use an OTP, insert “{0}” in the text of the SMS and ZignSec generates the code and replace it automatically. To validate that the user enters the correct code see section “Receiving SMS status” in this document. Example with OTP generation: text=Enter+the+following+code+to+log+in%3A+%7B0%7D SMS in plain text: “Enter the following code to log in: {0}” SMS to the phone: “Enter the following code to log in: 422423” The code has a time validity of 5 minutes and allows for up to three failed login attempts before blocking it. Use the below value to add a OTP-code in your message request. verify_code [Optional] By default ZignSec generates this 6 digit numeric value. If you prefer to use your own code can you override the default value by including a numeric value between 100 and 9999999. Example: to=547933 Upload the code entered on your website or in your app by using the Status SMS request and use the code value described below. code You can provide an user entered code to the API to validate it. This is preferable because we can do a better risk assessment. In example the correct OTP-code in the SMS is “12345” Example: https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c/12345 Check if the code has been successfully validated with the status given in the SMS Status response. sms.state Possible values are PENDING, FINISHED, VALID, INVALID. VALID and INVALID is used when OTP-code is generated, if not the final state is FINISHED.

Response

Each Send SMS request returns a response with status and details. Both the Send SMS and the Status request follow the same repsonse structure described below.

Keys and values

idA GUID value used to identify the web service request. The value is unique to each web service request, is randomly-generated by ZignSec, and is returned in the response message immediately following the web service request.
errorsA JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair of parameters is returned for each error. code Code for the error. List of codes is in table below. description A string that describes the type of error that occurred. If no errors occur, then this object is empty. errors : []
resultAn object that describes the result; it contains the following parameters: sms.state Possible values are PENDING, FINISHED, VALID, INVALID. VALID and INVALID is used when OTP-code is generated, if not the final state is FINISHED.
smsAn object that describes the status of the SMS. The following parameters can be found in this object. smsid The unique ID of the message that was sent. status.code Code for the error. List of codes is found below. status.description A string that describes the type of error that occurred. status.updated Time and date then last updated.

Table of response errors

CodeDescription
INVALID_TOInvalid “To”
INVALID_FROMInvalid “From”
INVALID_TEXTInvalid ”Text” length. The maximum length of text message that you can send is 2000 characters
INVALID_APPIDInvalid ”AppID”
MISSING_CONFIGYour account has a missing config, contact ZignSec for help
INVALID_REQUESTSomething unexpected has gone wrong, contact ZignSec for help

Table of statuses

CodeDescription
100Delivered to phone
101Delivered to SMSC
102Queued on SMSC
103Non-Delivered to SMSC
104Non-Delivered to Phone
105The message is pending

Example

{
	"id" : "89772638-c373-4cde-8742-946b24c8e0a6",
	"errors" : [],
	"result": {		
		"sms": {
	             "state": "PENDING"
		}
	},	
	"sms": {
		"SmsId": "5cc5484a-9903-49dd-817f-74003ce5f7a2",
		"status": {
			"code": 105,
			"description": "The message is pending",
			"updated": "2016-10-05T15:25:22.2144377+02:00”
		}
	}
}

Step 2. Check the delivery status

API

GET from https://env.zignsec.com/v2/mmessaging/id {/code}    where env is API or test and code is optional when OTP validation is performed. The id parameter in the URL is our SMS identification code, and should be the id in the response from the initiating send message API call.

Notification

As for all ZignSec APIs, you can either pick up the status of the message you with a GET request, or register a webhook to have ZignSec push a notification to you.

Response Body

The response body contains a JSON object with same parameters as in the response section. id The reference identifier that ZignSec generated and returned in its response to your POST to this web service request. This value uniquely identifies each ZignSec web service request. Example: https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c> code You can provide an user entered code to the API to validate it. This is preferable because we can do a better risk assessment.. In example the correct OTP-code in the SMS is “12345” Example: https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c/12345

GET Session results by Session Id

GET https://test.zignsec.com/v2/mmessaging/89772638-c373-4cde-8742-946b24c8e0a6/ HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/json
Host: test.zignsec.com
{
    "id": "89772638-c373-4cde-8742-946b24c8e0a6",
    "errors": [],
    "result": {
        "sms": {
            "state": "FINISHED"
        }
    },
    "sms": {
        "SmsId": "de3b3b09-1dc5-498c-adfc-8cef7b94c6b2",
        "status": {
            "code": 100,
            "description": "Delivered to phone",
            "updated": "2022-04-28T08:33:02.0429653Z"
        }
    },
    "relayState": "ZignSec"
}

GET Session validation results by Session Id and 4 digits code

GET https://test.zignsec.com/v2/mmessaging/89772638-c373-4cde-8742-946b24c8e0a6/12345 HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/json
Host: test.zignsec.com
{
    "id": "89772638-c373-4cde-8742-946b24c8e0a6",
    "errors": [],
    "result": {
        "sms": {
            "state": "VALID"
        }
    },
    "sms": {
        "SmsId": "de3b3b09-1dc5-498c-adfc-8cef7b94c6b2",
        "status": {
            "code": 100,
            "description": "Delivered to phone",
            "updated": "2022-04-28T08:33:36.764019Z"
        }
    },
    "relayState": "ZignSec"
}