Karix SMS JSON API user guide

Overview

This guide provides specifications of the JSON based API connectivity provided by Karix (previously known as mGage India) to Acoustic customers so that they can send their transactional SMS messages quickly. Familiarity and experience with invoking the HTTP API request using JSON payload is necessary to use this API.

Note: This API can only be used by those Acoustic clients whose organizations have been set-up to send SMS's using the Karix SMS gateway.

Features Supported By This API

These features are supported by this JSON API:

One 2 One (single message to single recipient)
One 2 Many (single message to multiple recipients)

Parameters supported by the JSON API call

Parameter	Description	Comments	JSON Key	Mandatory	Possible values	Default value
API Version	To specify the version of this JSON API		ver	Yes	1.0	1.0
API Access-Key	A unique key to identify the customer.	This will be generated by the Karix Provisioning team. Acoustic's provisioning team will provide this to the customer	key	Yes	XXX...X	Not applicable
Schedule time	The schedule date and time for the message to be sent out.	String representing the date and time in the below format 'yyyy-MM-dd HH:mm:ss'. Minimum schedule time is CurrentTime + 15 minutes. Maximum schedule time is CurrentDate + 3 months. Time is specified in India time zone.	sch_at	No	XXXXXX	null
MSIDSN	To specify the mobile number(s). Mobile numbers must be specified in E.164 format.	The mobile numbers will be represented as JSON array. For example, ["919620660000", "919620660001", “919620660002”]	dest	Yes	["919620660000", "919620660001", "919620660002"]	Not applicable
Message text	Message text to be sent out to mobile numbers	Text up to 800 characters long. The long message text is concatenated if supported by the mobile carrier and handsets.	text	Yes	XXX	Not applicable
From address	To specify the Source (Sender) ID.	Maximum length is 15.	send	Yes	XXX	Not applicable
Content type	Content type of the message.		type	No	PLAIN UNICODE	PLAIN
Send delivery notification	To specify about the Delivery Receipt (DLR) to be sent back or not. The DLR will be sent back in HTTP JSON API.	The client's backend web server address will be provisioned as part of the account setup.	dlr_reg	No	1/0	0
urltracking	To specify this message is having the URL tracked.	Allows the client to set up shortened URLs that can be tracked using the Karix portal. The associated ID is embedded in the outgoing message text.	url track	No	1/0	0

Note on content types:

By default, the API assume that the customer's request is on UTF-8 charset. If you want to send in a different charset, then you have to specify the charset in the HTTP request’s content-type.
The content typle (type parameter) can be any one of the following:
- PLAIN
- UNICODE

Sample SMS JSON API

One 2 One (Single Message to Single Recipient)

This JSON API example refers specifically to the sending of a single message to a single recipient.

{

  "ver": "1.0",

  "key": "xxxxxxxxxxxxx999xxxxx",

  "sch_at": "yyyy-MM-dd HH:mm:ss",

  "messages": [

    {

      "dest": ["919620660000"],

      "text": "Sample Text 1",

      "send": "Send 1",

      "type": "Plain",

      "dlr_req": "1",

      "urltrack": "1",

    }

  ]

}

**One 2 Many (Single Message to Multiple Recipients)((

One 2 Many SMS is basically a type of group SMS in which same message is broadcasted to a large number of recipients.
This feature enables the user to send a single message content to the multiple mobile numbers. In this scenario, all the predetermined mobile numbers will receive the same format of message content.
The mobile numbers will be represented as JSON array ["mobile1", "mobile2", "mobile3"]. For example, ["919620660000", "919620660001"]

This JSON API example refers specifically to the sending of a single message to mulitple recipients.

{

  "ver": "1.0",

  "key": "xxxxxxxxxxxxx999xxxxx",

  "sch_at": "yyyy-MM-dd HH:mm:ss",

  "messages": [

    {

      "dest": ["919620660000", "919620660001", "919620660002"],

      "text": "Sample Text 1",

      "send": "Send 1",

      "type": "Plain",

      "dlr_req": "1",

      "urltrack": "1",

    }

  ]

}

Response format

Sample success response

{

   "status": {

      "code": "200",

      "desc": "Request Accepted"

   },

   "ackid": "23423412341234",

   "time": "yyyy-MM-dd HH:mm:ss"

}

**Sample failure response

{

   "status": {

      "code": "-106",

      "desc": "Invalid credentials"

   },

   "ackid": "N/A",

   "time": "yyyy-MM-dd HH:mm:ss"

}

Status Codes for Responses

Status code	Status description	Comment
200	MSG_ACCEPTED	Request accepted
-999	INTERNAL_ERROR	Internal error
-101	API_VERSION_INVALID	Invalid API version
-102	INVALID_JSON	Invalid JSON
-103	IP_RESTRICTED	Invalid source IP
-104	ACCOUNT_EXPIRED	Account expired
-105	ACCOUNT_INACTIVATED	Account deactivated
-106	ACCOUNT_INVALID_CREDENTIALS	Invalid username or password
-108	SCHEDULE_OPTION_DISABLE	Scheduling feature disabled
-109	DESTINATION_EMPTY	Empty mobile number
-110	SCHEDULE_TIME_BEYOND_TIME_BOUND	Invalid mobile number
-111	DESTINATION_EMPTY	Empty mobile number
-112	DESTINATION_INVALID	Invalid mobile number
-113	MESSAGE_EMPTY	Empty message content
-114	INVALID_MSGTYPE	Invalid message type
-116	DLRTYPE_INVALID	Invalid DLR type
-120	URLTRACK_INVALID_OPTION	Invalid URL tracking option
-123	TRAI_BLOCKOUT_TIME	Cannot send message in TRAI blockout time
-124	SCHEDULE_TRAI_BLOCKOUT_TIME	Cannot schedule the message delivery time to TRAI blockout time

Sample format of possible error responses

Internal error
Error code: -999
Description: This error response is thrown whenever an internal error occurs.

{

  "status": {

    "code": "-999",

    "desc": "Internal Error"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid API version
Error code: -101
Description: This error response is shown when the user entered an invalid API version.

{

  "status": {

    "code": "-101",

    "desc": "Invalid API version"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid JSON
Error code: -102
Description: This error response is thrown when the JSON is Incomplete/not in proper JSON Format.

{

  "status": {

    "code": "-102",

    "desc": "Invalid JSON"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid source IP
Error code: -103
Description: This error response is thrown when the request from unauthorized source.

{

  "status": {

    "code": "-103",

    "desc": "Invalid source IP"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

**Account expired
Error code: -105
Description: This error response is thrown when the request is submitted from a deactivated account.

{

  "status": {

    "code": "-105",

    "desc": "Account Deactivated"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid credentials
Error code: -106
Description: This error response is thrown when the username / password is incorrect.

{

  "status": {

    "code": "-106",

    "desc": "Invalid credentials"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Scheduling feature disabled
Error code: -108
Description: This error response is thrown when the scheduling feature is disabled for that account

{

  "status": {

    "code": "-108",

    "desc": "Scheduling feature disabled "

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

**Invalid schedule time
Error code: -109
Description: This error response is thrown when the schedule time in the request is not in the expected format.

{

  "status": {

    "code": "-109",

    "desc": "Invalid schedule time"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Schedule Time Is Beyond the Time Bound
Error code: -110
Description: This error response is thrown when the schedule time is beyond the time bound (i.e. beyond 3 months).

{

  "status": {

    "code": "-110",

    "desc": "Schedule time is beyond the time bound"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

**Empty mobile number
Error code: -111
Description: This error response is thrown when the destination in the request is empty.

{

  "status": {

    "code": "-111",

    "desc": "Empty mobile number"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid mobile number
Error code: -112
Description: This error response is thrown when the destination number in the request is invalid.

{

  "status": {

    "code": "-112",

    "desc": "Invalid mobile number"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Empty message content
Error code: -113
Description: This error response is thrown when the message content is empty in the request.

{

  "status": {

    "code": "-113",

    "desc": "Empty message content"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid message type
Error code: -114
Description: This error response is thrown when the message type is unsupported / invalid.

{

  "status": {

    "code": "-114",

    "desc": "Invalid message type "

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid DLR type
Error code: -116
Description: This error response is thrown when the DLR type mentioned is invalid.

{

  "status": {

    "code": "-116",

    "desc": "Invalid DLR type"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Invalid URL tracking option
Error code: -120
Description: This error response is thrown when the URL Tracking option is invalid.

{

  "status": {

    "code": "-120",

    "desc": "Invalid URL tracking option"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

Cannot send message in TRAI blockout time
Error code: -123
Description: This error response is thrown when the customer has sent the messages at TRAI blockout time.

{

   "status": {

    "code": "-123",

    "desc": "Cannot send the message in TRAI blockout time"

   },

   "ackid": "N/A",

   "time": "yyyy-MM-dd HH:mm:ss"

}

Cannot schedule the message delivery time to TRAI blockout time
Error code: -124
Description: This error response is thrown whenever the message delivery time is scheduled to TRAI blockout time.

{

   "status": {

    "code": "-124",

    "desc": "Cannot Schedule the message delivery time to TRAI blockout time"

   },

   "ackid": "N/A",

   "time": "yyyy-MM-dd HH:mm:ss"

}