GET request to HTTP port:
http://1.1.1.1:8001/api?username=<username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>$command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>GET request to HTTPs port:
https://domainname:8002/api?username=<username>&password=<password>&ani=<ani>&dnis=<dnis>&message=<message>$command=submit&serviceType=<serviceType>&longMessageMode=<longMessageMode>POST request (credentials are part of the link) to HTTP port:
curl -H 'Content-Type: application/json' -X POST -d '{"ani":"dnis":"date":"message":"test"}' 'http://1.1.1.1:8001/api?command=submit&username=username&password=passwordPOST request (credentials are a part of the JSON body) to HTTP port:
curl -H 'Content-Type: application/json' -X POST -d '{"username":"username","password":"password","command":"submit","ani":"ani","dnis":"dnis","date":"message":"test"}' 'http://1.1.1.1:8001/api?'NOTE: To send multiple SMS messages, add several comma-separated DNIS to the <dnis> field.
| Parameter | Value | Required |
|---|---|---|
| command: | Request type. Possible values: "submit", "query", "mo". To send a message over HTTP, specify command=submit | Yes |
| dnis: | Destination number. Must be sent in international E.164 format (up to 15 digits allowed). If the field length exceeds 2048 symbols or 100 numbers, the incoming message will be rejected with the following code: 400 Bad Request (Destination number is too long). Multiple DNIS's cannot be used for longMessageMode=split_or_payload If multiple identical numbers are transferred in the field, the duplicates will not be sent further, even though message IDs will be issued for all successfully routed messages. | Yes |
| message: | Message text | Yes |
| password: | Password | Yes |
| serviceType: | Service type, provided by the System owner for the registered interconnection. Can be blank. The maximum length is 9 bytes | Yes |
| username: | Login | Yes |
| ani: | Caller ID. Technical limitation - alpha-numeric up to 32 symbols. Additional limitations can be caused by destination route peculiarities | No |
| dataCoding | Data coding scheme for sending the SMPP to the vendor. Format: integer. Optional. Allowed values are: 0, 1, 3, 6, 7, 8, 10, 14, where: 0: SMSC Default Alphabet (SMPP 3.4)/MC Specific (SMPP 5.0) 1: IA5 (CCITT T.50)/ASCII (ANSI X3.4) 3: Latin 1 (ISO-8859-1) 6: Cyrillic (ISO-8859-5) 7: Latin/Hebrew (ISO-8859-8) 8: UCS2 (ISO/IEC-10646) 10: ISO-2022-JP (Music Codes) 14: KS C 5601 | No |
| esmClass | corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0-255 | No |
| flash | Flag that indicates a flash message. Possible values are: 0 (regular message) and 1 (flash message that is shown on the screen and is not stored in the device memory). Note that the flag is merely written to the EDR (Technical details field) and does not change the message data coding. The flag value can be transmitted for MT message sending. The flag can also be changed with the help of translation rules. | No |
| longMessageMode: | Type of long message processing. Values allowed: cut (trim message text to 140 bytes): shortens the message leaving only first 140 bytes to be sent. split and split_sar — split the message according to the logics described below. The difference between them is in the header to be used, for split it is UDH header, for split_sar it is sar accordingly. single_id_split — split the message but return the message ID common for all segments payload — message_payload field is used for sending the message text. The splitting (options 2/3) depends on the coding: dataCoding = 0, 1 or 3: one message can contain up to 160 bytes. If more: segment count = 'message length in symbols / 153 symbols' (or: 'message length in bytes / 153 bytes') dataCoding 2, 4 - 7: one message can contain up to 140 bytes, if more – segment count = 'message length in symbols / 134 symbols' (or: 'message length in bytes / 134 bytes') dataCoding 8: one message can contain up to 140 bytes, if more – segment count = 'message length in symbols / 67 symbols' (as 1 symbol occupies 2 bytes, that is: 'message length in bytes / 134 bytes') split_or_payload: serves for sending long messages received over HTTP to SMPP vendors. The mode is not supported if several numbers have been received in the dnis parameter within a single request from the client. When the Send text in payload option is enabled in the vendor channel, the message will be sent in the payload field as a single submit_sm packet. Also, a single delivery report is expected for it, whereas the client will be sent as many reports as the number of received parts. Besides, a single EDR will be written, therefore, the bill by segments option must be set in the client product for correct billing of the client. The default value is "cut". | No |
| incMsgId (inc_msg_id) | The client message ID (64 symbols maximum) that can be used for incoming HTTP requests with longMessageMode=cut, longMessageMode=split, longMessageMode=split_sar or no longMessageMode (which equals to longMessageMode=cut). When the SMS switch receives this parameter it will use its value as a client ID. This will allow clients to use their ID to request information on the message if, for example, no routes are available. In case of long messages (when longMessageMode=split or longMessageMode=split_sar), the incoming parameter inc_msg_id will be one and the same for the entire message, whereas the SMS switch will split the message into several parts and use the same ID for each part, adding the part number to each of them. For example, if a message contains two parts and has the incoming message ID is inc_msg_id=1gfc4dd56cbndcj741xs, the SMS switch will process the messages with IDs 1gfc4dd56cbndcj741xs-1 and 1gfc4dd56cbndcj741xs-2. | No |
| srcTon, srcNpi, dstTon, dstNpi | the respective parameters for Sender ID and Destination number. Format: integer. Optional | No |
| priorityFlag | corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1. | No |
| registeredDelivery | corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1. | No |
| replaceIfPresentFlag | corresponds to the same name parameter in SMPP. Format: integer. Optional. Allowed values are: 0 and 1. | No |
| silent | Flag that allows sending silent SMS (message that arrives with no sound and is not displayed on the screen) Allowed values are: 0 and 1, where 0 means NOT silent. Any value other than 0 which has been set explicitly is treated as true, for example, silent=false is interpreted as silent=1. Whether the silent SMS arrives as a silent one to the end user depends on the vendor and the other carriers that handle it. | No |
In case of successful processing, the status in the header of the HTTP response is 200 OK. Response body contains the message_id.
Sample of a response in JSON format:
HTTP/1.1 200 OK
Content-Type: application/json
{"message_id":"alss-a1b2c3d4-e5f67890"}In case
1) the request contains more than one DNIS (comma-separated);
2) the longMessageMode=split/split_sar and the message is longer than 160/70 symbols (GSM/ Unicode respectively), the response will look as follows:
HTTP/1.1 200 OK
Content-Type: application/json
[{"dnis":"34511121","message_id":"5b4c46a8-8dc9-44b4-f55f-3bef56819305", "segment_num":"1"},{"dnis":"34511121", "message_id":"5b4c46a8-46bc-7ee6-4a16-7d4e5a0d14af","segment_num":"2"}]In case of rejected SMS (for example, no compatible routes found), the HTTP response status is 400 Bad Request. The response body contains a string describing the reason for rejection, for example NO ROUTES.
HTTP/1.1 400 Bad Request
Content-Type: text/html; charset=UTF-8
NO ROUTESIn case an incorrect user name or password is provided, the HTTP status is 401 Unauthorized. The response body contains the string describing the reason for rejection.
HTTP/1.1 401 Unauthorized
Content-Type: text/html; charset=UTF-8
not authorized (check login and password)If the service_type field exceeds 6 bytes, the response will look as follows:
HTTP/1.1 400 Bad request\n
Content-Type: text/html; charset=UTF-8\n
Service type is invalid\nIf a message is considered a loop in accordance with the Loop Detection functionality, the response will be as follows:
HTTP/1.1 508 Loop Detected
Content-Type: text/html; charset=UTF-8
loop detectedThe links below are intended for request of delivery reports over HTTP from the client side.
http://1.1.1.1:8001/api?
username=<username>&password=<password>&messageId=<messageId>&command=query
https://1.1.1.1:8002/api?
username=<username>&password=<password>&messageId=<messageId>&command=query| Parameter | Value |
|---|---|
| username: | Login |
| password: | Password |
| messageId: | Message identifier received with the submission response |
| command: | Request type. Must be set to "query" value. |
All parameters are obligatory.
In case of successful processing, the status in the header of the HTTP response is 200 OK. The response body contains the one of the following possible values:
| Parameter | Value |
|---|---|
| ENROUTE: | Message is in routing stage. The status can be returned to the client if the message is in the SENT status. |
| DELIVRD: | Message is delivered to the Subscriber. |
| EXPIRED: | Message storage period expired. |
| DELETED: | Message was deleted. |
| UNDELIV: | Message cannot be delivered. |
| ACCEPTD: | Message is accepted by SMSC. |
| UNKNOWN: | Unknown message status. Information on statuses is stored in the in-memory database for 24 hours (by default). Therefore, this status may be returned if the client has requested a status quite late and it was already removed from the memory. |
| REJECTD: | Message was rejected by SMSc. The status can also be returned for intern. |
| IM_EXPD | Delivery report was not received from the IM provider within the im_ttl timeout. |
Response sample:
HTTP/1.1 200 OK
Content-Type: application/json
{"status": "DELIVRD", "delivery_time": "20210922093309", "mccmnc": "214099", "error_code": "000", "system_delivery_time": "210922093309"}where delivery_time is the done date received from the vendor (if not received the field will be empty); mccmnc is the E212 code; error_code is the delivery error code; system_delivery_time is the delivery report receipt time by the System (in the format YYMMDDHHMMSS, for example: 210325153842).
The status can be requested within 24 hours after the message submission.
In case the message with the requested message ID is not found the response HTTP status is 200 OK. The response body contains the error description in the "status" field:
HTTP/1.1 200 OK
Content-Type: application/json
{"status": "UNKNOWN", "delivery_time": "", "mccmnc": ""}In case an incorrect user name or password is provided, the HTTP status is 401 Unauthorized. The response body contains the string describing the reason for rejection.
HTTP/1.1 401 Unauthorized
Content-Type: text/html;
charset=UTF-8 not authorized
(check login and password)This section contains allowed marker names for outgoing HTTP callbacks (sending of delivery report with the help of cURL in a generated script).
It is possible to specify the _noencode suffix for markers. This allows, for example, transmitting text without URL encoding to the client. Example:
curl 'http://1.1.1.1/api/callback/api?msg-id=$message_id$&state=$delivery_status$&reason-code=$result_code$&to=$dnis$&time=$done_date_noencode$&msg-id=$messageId$&mcc=$mcc$&mnc=$mnc$| Parameter | Description | Format | Allowed Values |
|---|---|---|---|
| ani | Destination address | string | |
| app_msg_id | Identifier of the submit that was sent to the client in the submit_sm_resp or HTTP response | string | |
| clientChannelId | Identifier of the submit that was sent to the client in the submit_sm_resp or HTTP response | integer | |
| country_name | Country Name | string | if not defined, the marker is replaced by "Undefined" |
| currency | Client account's currency | string | |
| delivery_status | Delivery status based on outgoing translations for the client side | string | |
| delivery_time | Time when the delivery report was generated by the switch | string | Date format: YYMMDDHHMMSS |
| dlvrResultCodeDescr | Response code description | string | |
| dnis | Sender ID | string | |
| done_date | Time value from the "done date:" field of the delivery report received from the vendor | string | Date format: YYMMDDHHMMSS. Depending on the date format in the source delivery report, the SS may be 00. Example: 2019-11-12Z08:06:18 |
| done_date_t | The message delivery time in the System timezone with an unrounded value of seconds (for example, 2021-02-23Z13:46:2 ) the same as done_date marker but with replacing the Z delimiter by T | string | Example: 2019-11-12T08:06:18 |
| message | Delivery report text generated by the switch | string | |
| message_id | Message identifier, including the common ID of a concatenated message if the switch correctly detected concatenation and successfully put together all message segments. | string | |
| mcc | MCC | string | |
| mccmnc | MCCMNC | string | |
| mnc | MNC | string | |
| mnc_no_zero | MNC without leading zeros | string | |
| net_name | Network name | string | if not defined, the marker is replaced by "Undefined" |
| part_amount | Number of message parts | string | number, from 1 and above |
| rate | Message cost in the client's currency | string | number; up to 5 decimal places are allowed |
| net_name | Network name | string | if not defined, the marker is replaced by "Undefined" |
| reportingKey | reporting key received in an Oracle Responsys request | string | |
| result_code | Error code from the delivery report received from the vendor | string | The default value is "000" |
| serviceType | For POIs with service string type='*' it is replaced with the service type received from the client in the initial submit request | string | |
| system_delivery_time | The delivery report send time to the client | string | Date format: YYMMDDHHMMSS |
Last updated: 12 Sep 2025