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

ParameterDescriptionCommentsJSON KeyMandatoryPossible valuesDefault value
API VersionTo specify the version of this JSON APIverYes1.01.0
API Access-KeyA unique key to identify the customer.This will be generated by the Karix Provisioning team. Acoustic's provisioning team will provide this to the customerkeyYesXXX...XNot applicable
Schedule timeThe 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_atNoXXXXXXnull
MSIDSNTo 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”]
destYes["919620660000", "919620660001", "919620660002"]Not applicable
Message textMessage text to be sent out to mobile numbersText up to 800 characters long. The long message text is concatenated if supported by the mobile carrier and handsets.textYesXXXNot applicable
From addressTo specify the Source (Sender) ID.Maximum length is 15.sendYesXXXNot applicable
Content typeContent type of the message.typeNoPLAIN UNICODEPLAIN
Send delivery notificationTo 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_regNo1/00
urltrackingTo 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 trackNo1/00

Note on content types:

  1. 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.
  2. 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 codeStatus descriptionComment
200MSG_ACCEPTEDRequest accepted
-999INTERNAL_ERRORInternal error
-101API_VERSION_INVALIDInvalid API version
-102INVALID_JSONInvalid JSON
-103IP_RESTRICTEDInvalid source IP
-104ACCOUNT_EXPIREDAccount expired
-105ACCOUNT_INACTIVATEDAccount deactivated
-106ACCOUNT_INVALID_CREDENTIALSInvalid username or password
-108SCHEDULE_OPTION_DISABLEScheduling feature disabled
-109DESTINATION_EMPTYEmpty mobile number
-110SCHEDULE_TIME_BEYOND_TIME_BOUNDInvalid mobile number
-111DESTINATION_EMPTYEmpty mobile number
-112DESTINATION_INVALIDInvalid mobile number
-113MESSAGE_EMPTYEmpty message content
-114INVALID_MSGTYPEInvalid message type
-116DLRTYPE_INVALIDInvalid DLR type
-120URLTRACK_INVALID_OPTIONInvalid URL tracking option
-123TRAI_BLOCKOUT_TIMECannot send message in TRAI blockout time
-124SCHEDULE_TRAI_BLOCKOUT_TIMECannot 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"

}