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.| 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 for JSON object. Example: Content-Type: application/x-www-form-urlencoded | Required |
| Host | Use test.zignsec.com for test environment and api.zignsec.com for production environment. 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. Example: to=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 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+message | Yes |
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
| 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_TEXT | Invalid ”Text” length. The maximum length of text message that you can send is 2000 characters |
| 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 | 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" : "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"
}