ZignSec

Messaging Sms/Verification

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 Second 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.

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 and.

Request Header

In order to send a message you need to authenticate yourself using the credentials given by Zignsec.

Authorization Specifies the ZignSec authorization that you get from ZignSec
Example: Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Required
Content-Type Specifies the media type of the request body data. Set to application/x-www-form-urlencoded. for post data and application/json if json object.
Example: Content-Type: application/x-www-form-urlencoded
Required
Host Use test.zignsec.com for test enviroment and api.zignsec.com for production enviroment.
Example: api.zignsec.com
Required

Request Body

This request contains:

Parameter Description Required
from This 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=ZignSec

Yes.
to The receiver´s phone number including country code, but not including a leading + or 00.

Exampleto=46123456789

Yes.
text The 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 5 SMS with 153 characters each for a total length of 756 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+message

Yes
            POST https://test.zignsec.com/v2/mmessaging HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/x-www-form-urlencoded
Host: test.zignsec.com
Content-Length: 71

to=46123456789&from=ZignSec&text=This+is+the+URL-encoded+message
        

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

id A 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.
errors A 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 : []
result An 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.
sms An 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

Code Description
INVALID_TO Invalid “To”
INVALID_FROM Invalid “From”
INVALID_APPID Invalid ”AppId”
MISSING_CONFIG Your account has a missing config, contact ZignSec for help
INVALID_REQUEST Something unexpected has gone wrong, contact ZignSec for help

Table of statuses

Code Description
100 CountryCode is invalid Delivered to phone
101 Delivered to SMSC
102 Queued on SMSC
103 Non-Delivered to SMSC
104 Non-Delivered to Phone
105 The message is pending

Example

            {
	"id" : "fa15b9c4-5156-4ba9-9516-eef03a15e16c",
	"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 https://test.zignsec.com/v2/mmessaging/fa15b9c4-5156-4ba9-9516-eef03a15e16c/12345 HTTP/1.1
Authorization: 00000000-e2a2-4968-b651-5352305c9fb0
Content-Type: application/x-www-form-urlencoded
Host: test.zignsec.com