REST API

Wstecz

Introduction

 

REST API is available at https://promosms.com/api/rest/

Each request consists of an API address, action name, and login and password separated by a colon and encoded in base64. Optionally, you can specify in what format the reply is to be returned. In addition, most of the actions require additional parameters transferred in the URL (GET method) or at the request header (POST method).

Encoding the login and password to the base64 form can be done, for example, in PHP using the following structure:

 

 

base64_encode($login . ':' . $password)

 

REST API syntax

View source
api_url/action_name/login_password[/format][?parameters]

 

Example send method

View source
https://promosms.com/api/rest/send-sms/bG9naW46cGFzc3dvcmQ=/json?text=Test%20message&type=3&recipients[]=500000001&recipients[]=500000002&sender=InfoSMS&special-chars=1&long-sms=1&date=1451602800&delivery-url=http%3A%2F%2Fexample.com%2Fsmsid%3D%25smsID%26report%3D%25report&user-index[]=testmsg1&user-index[]=testmsg2

In the above example, for readability, parameters are separated by a newline. However, they should not be used when calling REST requests

 

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - REST API adress

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - function

https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ= - base64 encoding login and password



Optionally, you can also add a reply format parameter (by default, text):
https://promosms.com/api/rest/send/bG9naW46cGFzc3dvcmQ=/json

 

Reply codes:

 

Status codes of method execution are individual for each method (applies to codes 1-399)

  • 0 - operation was successful
  • 00 00012 (110) - 11 11112 (6310) - executed with warnings. Warnings are stored in individual bits and at the same time there can be more than one
  • 100-199 - An error has occurred - not all the required data has been provided
  • 200-299 - An error has occurred - the values of the data transmitted is invalid
  • 300-399 - An error has occurred - the account or system configuration does not allow for the execution of the operation
  • 400 - an authentication error, which may be due to:
    • o an invalid login/password pair
    • o IP is not on the list of authorized addresses
    • o exceeded the number of login attempts (5 attempts per 15 minutes)
  • 401 - 403 - an unexpected error

 

Sending SMS messages

 

Sending SMS messages is done using send-sms

 

https://promosms.com/api/rest/send-sms

 

Available call methods: POST, GET

Input parameters:

  • text - string - the content of the sent message
  • type - integer - type of the SMS message sent. Permitted types are:
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FasterSMS
  • recipients[] - string[] - an array of message recipients. The string array must therefore contain recipients' phone numbers (each element of the array is another recipient)
  • sender - string (optional) - the name of the SMS message sender (displayed instead of the phone number). To use the sender’s own name, it must be registered in advance. For EkoSMS/FlashSMS, this parameter is optional
  • special-chars - boolean (optional) - by setting this value to 1, special characters will not be converted to their corresponding standard characters, but the message will be sent as transmitted to the system. It must be remembered that by transferring special characters in the contents of the SMS message, the length of the SMS message will be reduced from the standard 160 characters to 70. If, therefore, you want to make the PromoSMS platform remove all non-standard characters (special characters), you must specify the value of this variable to 0
  • long-sms - boolean (optional) - by setting this value to 1, the platform will accept for delivery also messages longer than 160 characters (or 70, if the special-chars variable is set to 1). Such messages will be delivered as a single message (colloquially: as a single SMS), but you should take into account the higher cost of delivery (depending on the number of component messages)
  • date - integer (optional) - a timestamp for the moment when the message is to be sent (a UNIX timestamp expressed in seconds)
  • delivery-url - string (optional) - the URL of the user’s server, to which message delivery reports are to be transmitted. The URL address may contain the following special variables, which will be replaced with the appropriate value by the system during the transmission of the report to the client server:
    • %smsID - ID of the sent message
    • %timestamp - the date of the report as a Unix timestamp
    • %number - phone number to which the message was sent
    • %report - ID report (1 means “delivered”)
    • %ownID - user's own ID
  • user-indexes[] - string[] (optional) - this parameter allows the user to define their own message identifiers. The number of the items in the array/vector must be equal to the number of the defined recipients of the message. Then each message will be assigned with the next item of the array. It is also possible to define one item in this array/vector, so that all sent messages are assigned with the same identifier
  • return-send-recipients - boolean (optional) - A flag that indicates whether the reply is to be returned to the details of each recipient

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

  • status (integer)
  • points (integer)
  • sent-sms-count (integer)
  • content-id (integer)
  • recipients-results
    • recipient-result[]
      • recipient (string)
      • sms-id (string)
      • own-id (string)
      • status (integer)

 

In addition, an XML document is compatible with the XSD definition below:

https://promosms.com/api/rest/send-sms.xsd

 

  • status - reply code
  • points - the cost of executed delivery (expressed in points)
  • sent-sms-count - the number of successfully sent messages
  • content-id - an identifier of content delivery
  • recipients-results[] - detailed delivery information (if the return-recipient-results input parameter is set to 1)
    • recipient - recipient's phone number
    • sms-id - an individual identifier of the message
    • own-id - an identifier assigned by the user
    • status - the status of message transmission (0 - transmitted, 210 – invalid number)

 

Final status of the send-sms function:

 

CodeDescription
012 (110) The message was sent for delivery in the future
102 (210) Part of the specified phone numbers is invalid
100 No recipients for delivery have been specified
101 Content not specified
102 Sender field not specified
103 UDH field not specified
104 No specified single object of the Message
200 All specified phone numbers are invalid
201 Sender name is too long
202 You cannot send messages to the past period
203 Number of own identifiers is incompatible with the number of recipients
204 The message is longer than 1 SMS message
205 Message is longer than 4 SMS messages (max.)
206 More than one recipient of the FasterSMS delivery has been specified
207 The content contains characters outside the Unicode set
208 One delivery contains recipients from various countries
209 Invalid message type
300 Account balance does not allow delivery
301 Sender's name has not been registered
302 Cannot send this type of message to the selected country
303 Account has not been adapted to use this API version

 

Example:

https://promosms.com/api/rest/send-sms/bG9naW46cGFzc3dvcmQ=/xml?text=Lorem+ipsum+dolor+sit+amet&type=1&recipients[]=500000001&recipients[]=500000002

 

Delivery reports

 

To query the system about the status of sent messages, you can use the get-reports

 

https://promosms.com/api/rest/get-reports

 

Available call method: GET

Input parameters:

 

  • indexes[] - strong[] (optional) - an array of message identifiers. Depending on the value of the index-type field, identifiers are smsId, own user IDs (userIndex) or content identifiers (contentID)
  • from-time - integer (optional) - time (as a Unix timestamp), from which you want to get information about the status codes of sent messages
  • to-time - integer (optional) - time (as a Unix timestamp), to which you want to get information about the status codes of sent messages
  • index-type - integer (optional) - type of identifier
    • 0 - smsId
    • 1 - userIndex
    • 2 - contentId
  • limit - integer (optional) - option useful when you need to retrieve a large number of status codes (e.g. several tens of thousands). Then you can limit the number of the returned items in the array.
  • offset - integer (optional) - this field determines the point from which the array is to be returned. The value of this field is taken into account only when the "limit" parameter is applied.

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • reports
    • report[]
      • recipient (string)
      • sms-id (string)
      • own-id (string)
      • content-id (integer)
      • status (integer)
      • last-update-time (integer)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/get-reports.xsd

 

  • status - reply code
  • reports[] - an array of reports
    • recipient - recipient's phone number
    • sms-id - a unique message ID
    • own-id - an identifier assigned by the user
    • content-id - an identifier of content
    • status - delivery status
      • 0 - message waiting to be sent
      • 4, 8 - message has been sent
      • 1 - message has been delivered to the recipient
      • 2, 16 - message has not been delivered - the most common causes of this status are incorrect phone number or too long inactivity of the recipient's phone
    • lastUpdateTime - status last update time,

 

Final status of get-reports:

 

CodeDescription
012 (110) Some of message identifiers are incorrect
100 Identifier type not specified
101 Message identifiers not specified
200 All specified identifiers are invalid
201 Invalid timestamp
202 Invalid identifier type
203 Invalid "limit” parameter value
204 Invalid "offset” parameter value

 

Example:

 

https://promosms.com/api/rest/get-reports/bG9naW46cGFzc3dvcmQ=/xml?from-time=1433109600&to-time=1435701600

 

Receiving replies

 

In the case of EkoSMS delivery, the recipient of the message can reply. Such replies are available through both the Panel SMS and REST APIs.

 

Receiving messages is done by calling get-inbox

 

https://promosms.com/api/rest/get-inbox

 

Available call method: GET

 

Input parameters:

 

  • last-message-id - integer (optional) - each received SMS message has a unique identifier in the form of a number. If you want to receive messages only from the specified message with a known identifier - please specify it here. Therefore, if when receiving the message the last read message was numbered 359 and now you want the function to only return newer messages – then the value of this parameter should be given as 359.
  • from-time - integer (optional) - if you want to retrieve all messages from a specified moment instead of using the message ID, you must specify it here as a Unix timestamp.
  • content-id - integer (optional) - if this parameter is set, replies are returned only to messages with the specified content identifier
  • sms-id - string (optional) - a unique message identifier
  • own-id - string (optional) - message identifier assigned by the user

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • inbox-messages
    • inbox-message[]
      • message-id (integer)
      • sender (string)
      • message (string)
      • original-message (string)
      • receive-time (integer)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/get-inbox.xsd

 

  • status - reply code
  • inbox-messages[] - the array of replies
    • message-id - reply identifier
    • sender - phone number of the reply sender
    • message - reply content
    • original-message - the content of the message to which the reply relates
    • receive-time - the time the message has been received (as a Unix timestamp)

 

Final status of get-inbox:

 

CodeDescription
012 (110) No new replies
200 Invalid reply ID
201 Invalid timestamp
202 Invalid content ID

 

Example:

 

https://promosms.com/api/rest/get-inbox/bG9naW46cGFzc3dvcmQ=/xml?from-time=1433109600

 

Checking account status

 

The account status can be checked by calling the get-balance

 

https://promosms.com/api/rest/get-balance

 

Available call method: GET

 

This function does not accept additional input parameters.

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • points-available (integer)
  • points-blocked (integer)
  • points-credit (integer)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/get-balance.xsd

 

  • status - reply code
  • points-available - the number of points available for use
  • points-blocked - the number of blocked points (due to delivery schedule)
  • points-credit - number of granted credits

 

Final status of get-balance:

 

CodeDescription
300 The account is not suitable for use with this API version

 

Example:

 

https://promosms.com/api/rest/get-balance/bG9naW46cGFzc3dvcmQ=/xml

 

Converting the message

 

While sending, the message is converted to the GSM standard, and then the number of component messages and the cost of such delivery is calculated. This conversion is done by calling convert-message.

 

https://promosms.com/api/rest/convert-message

 

Available call method: GET

 

Input parameters:

 

  • text - string - message, on the basis of which the number of characters and the number of SMS components is to be calculated
  • special-chars - boolean - if the parameter is set to “true”, then special characters are permitted in the message and they will not be replaced with counterparts in standard characters. If, however, it is set to “false”, then all special characters will be converted, and only then the length of messages and the number of component SMS will be calculated.
  • long-sms - boolean (optional) - if this field is set to “false”, the message will be cut to the length of one sms message.
  • sms-type - integer (optional) - the type of the SMS message. If this field, together with one of the country-code / country-prefix / country-name fields is not empty, the reply will include the cost of sending this message to a single recipient
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FastSMS
  • country-code - string (optional) - the country code of the recipient in the form of two letters
  • country-prefix - string (optional) - the recipient country prefix
  • country-name - string (optional) - the name of the recipient’s country

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • chars-number (integer)
  • sms-parts (integer)
  • text (string)
  • points (float)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/convert-message.xsd

 

  • status - reply code
  • chars-number - the total number of characters in the message
  • sms-parts - the number of component SMS messages
  • text - message content. If in the input parameters, the bSpecialChars value is set to “false”, then not the original message will be returned here, but the converted message
  • points - calculated cost of delivery (if the message type and country of delivery are specified in the request)

 

Final status of convert-message:

 

CodeDescription
100 Not specified content
101 Type of SMS message not specified
200 Message too long (exceeding 4 component SMS messages)
201 Various countries of delivery have been specified
202 The specified country of delivery does not exist
300 Sending this type of messages to a specified country is not available

 

Example:

 

https://promosms.com/api/rest/convert-message/bG9naW46cGFzc3dvcmQ=/xml?text=Puść+mą+dłoń!+Gnij+schab,+frytkę!+Zwóź+żel!&special-chars=0

 

Validating the numbers

 

validate-numbers method makes it possible to validate numbers in terms of syntax. Therefore, we check if, for example, number 504304204 has the correct form and if this number is possible.

 

https://promosms.com/api/rest/validate-numbers

 

Available call method: GET

 

Input parameters:

 

  • country-prefix - the prefix of the country from which a call is initiated. For example, if it is 48, then the following numbers are treated as Polish numbers: “512345678”, “48512345678”, “48512345678”. In addition, this is the same number recorded in different ways. However, if the field is set to 49, then only the latest example will be treated as a Polish number.
  • numbers[] - an array/vector of numbers. If the number has a different country prefix than the number specified in the countryPrefix field, then use the + (plus) symbol

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • numbers
    • number[]
      • original-number (string)
      • is-valid (boolean)
      • is-valid-for-region (boolean)
      • probably-exists (boolean)
      • country-prefix (string)
      • country-code (string)
      • formatted (string)
      • type (integer)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/validate-numbers.xsd

 

  • status - reply code
  • numbers[] - an array with detailed information about the phone number
    • original-number - the form in which the number has been specified in the request
    • is-valid - the flag that determines if the number is correct
    • is-valid-for-region - the flag that specifies if the number belongs to a specified prefix zone
    • probably-exists - the flag that determines if the number is probably true
    • country-prefix - country prefix
    • country-code - the country code in the form of two letters
    • formatted - a phone number with a country prefix
    • type - type of phone number:
      • 0 - Landline phone number
      • 1 - Mobile phone number
      • 2 - Landline or mobile phone number
      • 3 - Toll-free number (e.g. the number with a 800 ... prefix)
      • 4 - Premium rate number
      • 5 - The cost of the call is shared between the recipient and the sender (e.g. the number with a 801 ... prefix)
      • 6 - VoIP number
      • 7 - it is possible that one number is also the number of the mobile phone/landline phone(see: http://en.wikipedia.org/wiki/Personal_Numbers )
      • 8 - Pager
      • 9 - the so-called Universal Access Numbers or Company Numbers (One company phone number, but the connection can be properly switched over)
      • 10 lub -1 - Incorrect or different number, unidentified number type

 

Final status of validate-numbers:

 

CodeDescription
012 (110) Some of the specified numbers are invalid
102 (210) All specified numbers are invalid
100 No phone numbers have been specified

 

Example:

 

https://promosms.com/api/rest/validate-numbers/bG9naW46cGFzc3dvcmQ=/xml?country-prefix=48&numbers[]=504304204

 

Adding contacts

 

REST API allows you to add contacts to the Address Book using add-contacts

 

https://promosms.com/api/rest/add-contacts

 

Available call method: POST

 

Input parameters:

 

  • contacts[] - string[] - an array of phone numbers
  • groups[] - string[] - an array of identifiers contact groups
  • create-groups-if-not-exist - boolean - the flag that specifies whether or not to create a new group when the value specified in the "groups" field does not exist in the system

 

Reply:

 

If you select the reply in the XML or JSON format, the result is compatible with the following scheme:

 

  • status (integer)
  • contacts-count (integer)

 

In addition, an XML document is compatible with the XSD definition below:

 

https://promosms.com/api/rest/add-contacts.xsd

 

  • status - reply code
  • contacts-count - the number of contacts added

 

Final status of add-contacts

 

CodeDescription
100 Contacts not specified
101 No phone number in the contact
200 Invalid phone numbers
300 The account does not have a specified default delivery country

 

Example:

 

https://promosms.com/api/rest/validate-numbers/bG9naW46cGFzc3dvcmQ=/xml?contacts[]=504304204&groups[]=klienci