Overview

This guide provides specifications of the JSON based API connectivity provided by Karix (previously known as mGage India) to IBM 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 IBM 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 name Description Comments JSON Key Is 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. IBM’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
MSISDN 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 contecated if supported by the mobile carrier and handsets. text Yes XXX Not applicable
From Address To specify the Source (Sender) ID Max 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 set-up. 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. urltrack No 1/0 0

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 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 of Password
-108 SCHEDULE_OPTION_DISABLE

Scheduling feature disabled

-109 SCHEDULE_INVALID_TIME Invalid schedule time
-110 SCHEDULE_TIME_BEYOND_TIME_BOUND Schedule time is beyond the time bound
-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: -104 Description: This error response is thrown when the request is submitted from an expired account.

{

  “status”: {

    “code”: “-104”,

    “desc”: “Account Expired”

  },

  “ackid”: “N/A”,

  “time”: “yyyy-MM-dd HH:mm:ss”

}

Account Deactivated

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”

}

Join The Discussion

Your email address will not be published. Required fields are marked *