SMS API description

1. General description
2. Basic requirements
3. Sending SMS
4. Checking SMS sending summary



1. General description

SMS API provides the possibility to send SMS messages and check message
delivery status from your own applications. SMS messages can be sent to
one or more recipients at one time.

Communication with the API uses the SOAP protocol. SOAP client
libraries can be found for most development environments. SOAP
communication supported over http and https protocols.

In addition to this description we provide examples written in Perl
and PHP.



2.  Basic requirements

SMS API provided with the SOAP protocol. 

WSDL description of API available at
http://sms.diamondcard.us/doc/sms-api.wsdl

API requests should be send to sms.diamondcard.us over http or https
protocol.

- All parameters are case sensitive.
- All API requests should include Account Id and PIN code.
- To use this service your account should be active and have
enough funds in your account.

Phone numbers should be specified in e.164 format. Do not include any
international dialing code prefixes like 00 or 001, etc. 
Proper example for a USA number: 13031231234



3. Sending an SMS

For sending an SMS you should specify:

  AccId - your Account Id.

  PinCode - your PIN code.

  MsgTxt - message text you want to send. Message which exceed 160
           chars will be split by 160 chars and delivered in separate
           SMS messages.

  SendFrom - phone number you are sending SMS from.

  Destination - phone number or list of phone numbers to send message to. Max number of destinations is 100

Additional parameters may be used when message sent to several phone
numbers:

  IgnoreInvNumbers - By default phone numbers are verified before sending.
                     No message will be sent if at least one number
                     is invalid. If this parameter set to 1, messages
                     will be sent to all valid phone numbers in the
                     list with all invalid phone numbers being ignored.

  IgnoreInsufBalance - By default you should have enough funds in your
  		     account for entire SMS sending, otherwise SMS
  		     sending will be rejected. If this parameter set
  		     to 1 sending will start and go on till you run out
  		     of funds in your account.

Return value:
       
  On success  
      ErrCode - empty.

      SendingId - sending Id. This Id can be used for checking sending
                  status.

  On error
      ErrCode - one of the following:
         INVDEST - invalid destinations error. List of invalid phone
	           numbers available at 'InvalidDestinations' array.
         LOWBALANCE - Insufficient balance.
         NOTAVAIL - Service not available.
         ERR - misc errors. More details available at ErrMsg.

      ErrMsg - error description text.

      InvalidDestinations - When ErrCode=INVDEST this field contains
                            array of invalid phone numbers.



4. Checking SMS sending summary

For checking SMS sending summary you should specify:

  AccId - your Account Id.

  PinCode - your PIN code.

  SendingId - sending Id for which you request summary report.


Return value:

  On success  
      ErrCode - empty.

      Queue - number of messages in queue.

      Sent - number of sent messages.

      Delivered - number of delivered messages (if available).

      Failed -  number of failed messages.

      Cost - how much this sending costs.

      Currency - currency code for Cost.

  On error
      ErrCode - one of the following:
         ERR - misc errors. More details available at ErrMsg.

      ErrMsg - error description text.